# Quickstart: Empty State Consistency Pass

**Feature**: 122-empty-state-consistency | **Date**: 2026-03-08

## Scope

Unify the empty-state experience across six primary Filament list pages:
- Policies
- Backup Sets
- Restore Runs
- Backup Schedules
- Workspaces
- Alert Deliveries

The pass adds complete empty-state content (heading, description, icon, CTA), keeps existing RBAC behavior, updates the affected UI action-surface contract where needed, and adds focused regression coverage.

## Implementation order

1. Update the in-scope resource `table()` definitions so each list owns its empty-state heading, description, icon, and CTA whenever Filament supports it.
2. Collapse or remove list-page-only empty-state helper responsibility where it would otherwise split the contract across resource and page classes.
3. Keep existing header CTA placement behavior intact so the CTA remains in the empty state only when there are no rows and relocates to the header when rows exist for create-capable surfaces.
4. For `AlertDeliveryResource`, add the guided empty state, update the action-surface declaration to satisfy `ListEmptyState` rather than exempting it, and preserve the documented no-header-action exemption once rows exist.
5. Add or extend per-resource tests for empty-state copy, CTA presence, CTA outcomes, and capability-aware visibility or disabled behavior.
6. Update shared guard and placement tests where the changed surfaces should now be covered explicitly, including representative populated-state regressions.
7. Perform manual light/dark visual verification and attach evidence to the PR or review.
8. Run focused Sail-based tests and Pint.

## Primary files to modify

- [app/Filament/Resources/PolicyResource.php](../../../app/Filament/Resources/PolicyResource.php)
- [app/Filament/Resources/PolicyResource/Pages/ListPolicies.php](../../../app/Filament/Resources/PolicyResource/Pages/ListPolicies.php)
- [app/Filament/Resources/BackupSetResource.php](../../../app/Filament/Resources/BackupSetResource.php)
- [app/Filament/Resources/BackupSetResource/Pages/ListBackupSets.php](../../../app/Filament/Resources/BackupSetResource/Pages/ListBackupSets.php)
- [app/Filament/Resources/RestoreRunResource.php](../../../app/Filament/Resources/RestoreRunResource.php)
- [app/Filament/Resources/RestoreRunResource/Pages/ListRestoreRuns.php](../../../app/Filament/Resources/RestoreRunResource/Pages/ListRestoreRuns.php)
- [app/Filament/Resources/BackupScheduleResource.php](../../../app/Filament/Resources/BackupScheduleResource.php)
- [app/Filament/Resources/BackupScheduleResource/Pages/ListBackupSchedules.php](../../../app/Filament/Resources/BackupScheduleResource/Pages/ListBackupSchedules.php)
- [app/Filament/Resources/Workspaces/WorkspaceResource.php](../../../app/Filament/Resources/Workspaces/WorkspaceResource.php)
- [app/Filament/Resources/Workspaces/Pages/ListWorkspaces.php](../../../app/Filament/Resources/Workspaces/Pages/ListWorkspaces.php)
- [app/Filament/Resources/AlertDeliveryResource.php](../../../app/Filament/Resources/AlertDeliveryResource.php)

## Likely test files

- [tests/Feature/Filament/CreateCtaPlacementTest.php](../../../tests/Feature/Filament/CreateCtaPlacementTest.php)
- [tests/Feature/Guards/ActionSurfaceContractTest.php](../../../tests/Feature/Guards/ActionSurfaceContractTest.php)
- [tests/Feature/PolicySyncStartSurfaceTest.php](../../../tests/Feature/PolicySyncStartSurfaceTest.php)
- [tests/Feature/BackupScheduling/BackupScheduleLifecycleAuthorizationTest.php](../../../tests/Feature/BackupScheduling/BackupScheduleLifecycleAuthorizationTest.php)
- [tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php](../../../tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php)

## Validation commands

```bash
vendor/bin/sail artisan test --compact tests/Feature/Filament/CreateCtaPlacementTest.php
vendor/bin/sail artisan test --compact tests/Feature/PolicySyncStartSurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/BackupScheduling/BackupScheduleLifecycleAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
vendor/bin/sail bin pint --dirty --format agent
```

## Expected outcome

- Every in-scope list page shows a deliberate, contextual empty state.
- Each empty state has exactly one CTA and keeps existing authorization behavior.
- `AlertDeliveryResource` no longer relies on an empty-state exemption.
- Existing populated-table behavior and CTA-placement behavior remain intact, with Alert Deliveries preserved as the only documented no-header-action exemption.
- Light/dark visual QA evidence is attached to review artifacts, not committed to the repository.
