TenantAtlas/specs/125-table-ux-standardization/spec.md

Feature Specification: Filament Table UX Standardization & List Consistency

Feature Branch: 125-table-ux-standardization
Created: 2026-03-08
Status: Draft
Input: User description: "Spec 125 — Filament Table UX Standardization & List Consistency"

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes: All Filament table surfaces under /admin, /admin/t/{tenant}/..., and /system that render resource lists, relation manager tables, table widgets, custom table pages, or picker tables
• Data Ownership: Both workspace-owned and tenant-owned records are affected only at the presentation and interaction layer; this feature does not redefine underlying ownership or introduce new record types
• RBAC: Existing workspace membership, tenant membership, plane separation, and capability gates remain unchanged; the standard applies only within each surface’s current authorization boundaries

User Scenarios & Testing (mandatory)

User Story 1 - Scan Core Lists Predictably (Priority: P1)

As an operator moving between major product lists, I can rely on a consistent default table structure so I can find, sort, and compare records without relearning each screen.

Why this priority: Predictable list behavior is the core value of the feature. If major tables still feel inconsistent, the repo-wide standardization effort fails even if individual tables improve cosmetically.

Independent Test: Can be fully tested by updating one critical list page to follow the standard and verifying that its primary identifier is searchable and sortable, low-value technical detail is not dominant by default, and the table has a domain-specific empty state.

Acceptance Scenarios:

1. Given a critical product table with multiple records, When the user opens the page, Then the table presents a calm default view with a clear primary identifier, meaningful contextual columns, and technical detail kept secondary.
2. Given a populated critical table, When the user sorts by the primary identifier or recency field, Then the list responds in a way that matches the table’s domain purpose.

---

User Story 2 - Keep List Context Across Refresh (Priority: P2)

As a user investigating records over several page loads, I can refresh or return to key list pages without losing my search, sort, or filter context.

Why this priority: Losing table state creates repeated work and breaks operational flow. Persistence is one of the clearest gaps identified in the audit and materially affects day-to-day usability.

Independent Test: Can be tested by applying search, sort, and filters on a resource list, refreshing the page, and confirming that the list reopens in the same state.

Acceptance Scenarios:

1. Given a resource list with an active search term, sort order, and filter selection, When the user refreshes the page, Then the same list context remains active.
2. Given a user returns to a key resource list after navigating away, When the page loads again in the same session, Then the previously chosen list state is preserved.

---

User Story 3 - Reveal Detail Only When Needed (Priority: P3)

As an advanced operator, I can access technical fields such as identifiers and timestamps when needed without having those fields dominate every list by default.

Why this priority: Enterprise operators still need detail, but the product should present it on demand instead of overwhelming the default table surface.

Independent Test: Can be tested by opening a standardized table, confirming that technical detail is hidden by default, and then exposing the detail without losing access to the record’s primary context.

Acceptance Scenarios:

1. Given a standardized list that contains technical identifiers or low-frequency metadata, When the user opens column controls, Then those detail fields are available without being forced into the default layout.
2. Given a table with long identifiers or technical strings, When the user inspects the list, Then those values remain readable and accessible without breaking the page layout.

Edge Cases

• When a table has no records at all, it shows a domain-specific empty state with a clear explanation and only RBAC-allowed next steps.
• When a table contains relation-backed or computed fields that would create unacceptable sort or search cost, the standard allows a documented exception instead of forcing an expensive interaction.
• When a cross-tenant or cross-workspace list is shown, the default visible columns still preserve enough context to distinguish records safely.
• When exact chronology matters more than quick scanning, the table may keep an absolute time presentation as a documented exception to the general relative-time convention.

Requirements (mandatory)

Constitution alignment (required): This feature does not introduce Microsoft Graph calls, new write behavior, queue or schedule behavior, or OperationRun usage. It standardizes existing table UX on already-authorized screens only.

Constitution alignment (RBAC-UX): This feature touches both the tenant/admin plane and the platform plane, but it does not change authorization semantics. Non-membership remains deny-as-not-found, capability denial remains unchanged where it already applies, and all existing action-level server-side authorization must remain intact. Any new empty-state action shown on a surface must stay capability-gated and tenant-safe.

Constitution alignment (BADGE-001): Existing centralized badge semantics for status, outcome, severity, and boolean-like signals remain the source of truth. The standard may improve consistency of where badges appear in tables, but it must not introduce local badge vocabularies or ad-hoc status mappings.

Constitution alignment (Filament Action Surfaces): This feature satisfies the Action Surface Contract by preserving each table’s existing action architecture as table-local behavior. The scope is limited to list consistency, empty states, pagination, persistence, and column visibility; row actions, bulk actions, header actions, and inspection affordances remain explicit per surface and are not globally redesigned.

Constitution alignment (UX-001 — Layout & Information Architecture): This feature directly supports the table portions of UX-001 by requiring meaningful empty states and consistent search, sort, and filtering behavior for core dimensions. It does not change create, edit, or view form layout patterns.

Functional Requirements

• FR-001: The system MUST define and document a repo-wide table standard for all production Filament list surfaces.
• FR-002: The standard MUST classify visible table columns into Primary, Context, and Detail tiers as a review and implementation convention.
• FR-003: Every production table MUST expose a searchable primary identifier unless a documented exception establishes that search provides no user value for that surface or would introduce unacceptable query cost.
• FR-004: Every production table MUST define an explicit default sort unless a documented exception is required for domain or query-safety reasons.
• FR-005: Meaningful identifiers, recency fields, statuses, and operational counts MUST be sortable when doing so is useful and safe for the underlying query.
• FR-006: Technical identifiers, low-frequency metadata, and secondary timestamps MUST not dominate the default list surface and SHOULD be available as on-demand detail where practical.
• FR-007: General-purpose tables SHOULD present no more than seven columns by default unless a denser default view is explicitly justified.
• FR-008: Timestamp, null-value, and identifier presentation MUST follow consistent product-wide rules so similar values scan the same way across tables.
• FR-009: Every production table MUST provide a domain-specific empty state with clear explanatory copy, and it MUST include a next step only when one is meaningful and authorized.
• FR-010: Pagination options and default page sizes MUST follow explicit conventions by table class rather than relying on inconsistent implicit defaults.
• FR-011: The designated critical resource lists (TenantResource, PolicyResource, BackupSetResource, BackupScheduleResource, ProviderConnectionResource, FindingResource, and OperationRunResource) MUST preserve search, sort, and filter state across refresh within the same session.
• FR-012: The standard MUST reduce default horizontal overload by moving lower-value detail out of the initial view before any cosmetic workaround is considered.
• FR-013: The rollout MUST not worsen known query-risk tables by forcing expensive sorts, searches, or row-level computations without review.
• FR-014: The feature MUST preserve existing RBAC behavior, tenancy boundaries, action semantics, and audit expectations for every affected table surface.
• FR-015: The rollout MUST be phased so that conventions and critical high-value tables are addressed before the remaining table surface is aligned.
• FR-016: Future table changes MUST be reviewable against the same standard so new list surfaces do not drift back to ad hoc behavior.

UI Action Matrix (mandatory when Filament is changed)

If this feature adds/modifies any Filament Resource / RelationManager / Page, fill out the matrix below.

For each surface, list the exact action labels, whether they are destructive (confirmation? typed confirmation?), RBAC gating (capability + enforcement helper), and whether the mutation writes an audit log.

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Resource list tables	app/Filament/Resources/**/Pages/List*.php	Existing table-local actions retained	Existing row inspection affordance retained per resource	Existing resource-local actions retained	Existing grouped bulk actions retained where already supported	Added or refined per table when meaningful and authorized	Unchanged by this spec	Unchanged by this spec	Unchanged	Standardizes list behavior only; no action redesign
Relation manager tables	app/Filament/Resources/**/RelationManagers/*.php	Existing relation-manager actions retained	Existing table-local inspection pattern retained	Existing relation-manager row actions retained	Existing grouped bulk actions retained where applicable	Added or refined per table when meaningful and authorized	Unchanged by this spec	Unchanged by this spec	Unchanged	Detail visibility and pagination are standardized without changing mutation semantics
Table widgets and custom table pages	app/Filament/Widgets/.php and app/Filament/Pages/.php	Existing page or widget actions retained	Existing inspection affordance retained where records are inspectable	Existing row actions retained	Existing grouped bulk actions retained where applicable	Added or refined per surface when meaningful and authorized	Unchanged by this spec	Not applicable unless the page already provides forms	Unchanged	Read-only or operational surfaces may have no row actions; this spec does not force them
Picker or selection tables	app/Livewire/** and table-backed selection pages	Existing selection or header actions retained	Existing selection affordance retained	Existing selection-related row actions retained	Existing grouped bulk actions retained where applicable	Added only when it helps a blocked user recover	Unchanged by this spec	Unchanged by this spec	Unchanged	This spec standardizes calm defaults and pagination, not picker workflow semantics

Key Entities (include if feature involves data)

• Table Surface: Any production Filament-backed list surface, including resource lists, relation managers, widgets, custom pages, and picker tables.
• Column Visibility Tier: The conceptual classification of a column as Primary, Context, or Detail, used to decide whether it should be dominant, visible by default, or available on demand.
• Table Behavior Profile: The combination of default sort, search scope, empty-state behavior, pagination, state persistence, and overflow handling expected for a given table.
• Documented Exception: A justified, reviewable deviation from the standard where domain clarity, tenant safety, or query cost makes the default rule inappropriate.

Assumptions

• The existing audit inventory of approximately 36 production tables is sufficiently accurate to drive phased rollout planning, with minor recount differences allowed during implementation.
• Existing action labels, filters, query scopes, and badge mappings remain table-local unless a later spec proves a shared change is required.
• Critical rollout tables include TenantResource, PolicyResource, BackupSetResource, BackupScheduleResource, ProviderConnectionResource, FindingResource, OperationRunResource, and BackupItemsRelationManager; query-risk system pages such as Directory/Workspaces remain in scope for the broader rollout with documented exceptions where needed.
• Resource-list persistence is mandatory in this phase, while broader persistence beyond those surfaces may be adopted later only where it fits cleanly.

Dependencies

• The feature depends on an up-to-date inventory of production table surfaces and their current behavior gaps.
• The feature depends on retaining current authorization policies, capability registries, and centralized badge semantics during rollout.
• The feature depends on performance review of relation-backed and computed columns before new sort or search behavior is enabled.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In the post-rollout audit, 100% of production tables have an explicit default sort or a documented exception.
• SC-002: In the post-rollout audit, 100% of production tables provide a domain-specific empty state.
• SC-003: At least 90% of general-purpose production tables present seven or fewer columns by default unless a documented exception exists.
• SC-004: On all designated critical resource lists, a user can refresh the page without losing the current search, sort, and filter context during the same session.
• SC-005: In manual QA of critical tables, an operator can reach any hidden technical identifier or timestamp needed for troubleshooting in two interactions or fewer.