TenantAtlas/specs/122-empty-state-consistency/spec.md

Feature Specification: Empty State Consistency Pass

Feature Branch: 122-empty-state-consistency
Created: 2026-03-08
Status: Ready for Implementation
Input: Spec 122 — Empty State Consistency Pass (Unified empty states across all primary list pages)

Clarifications

Session 2026-03-08

• Q: What should the single empty-state CTA be for the read-only Alert Deliveries list? → A: Use “View alert rules” as the single CTA.
• Q: How should empty-state CTA visibility behave for members who lack the required capability? → A: Preserve existing per-resource behavior (disabled or hidden), but require explanation when shown disabled.
• Q: Where should the final empty-state configuration live? → A: Prefer resource table() definitions for empty-state heading/description/icon/action, and allow page helpers only when technically required.
• Q: How should screenshots and visual QA evidence be handled for this feature? → A: Attach screenshots / visual QA evidence to the PR or review, not as committed repo artifacts.

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • Admin UI list pages: Policies, Backup Sets, Restore Runs, Backup Schedules, Workspaces, Alert Deliveries
• Data Ownership:
  • Tenant-owned lists: Policies, Backup Sets, Restore Runs, Backup Schedules
  • Workspace-owned / workspace-context lists: Workspaces
  • Workspace-context monitoring history list: Alert Deliveries (may include tenant-bound rows; tenant entitlement still applies)
• RBAC:
  • Membership isolation: non-members are deny-as-not-found (404 semantics)
  • Capability gating: members without the required capability receive authorization denial (403 on execution); UI may show disabled actions with explanatory tooltip
  • Empty-state primary actions MUST remain capability-aware and MUST use the existing UI enforcement helpers already used by each module

User Scenarios & Testing (mandatory)

User Story 1 - First-run clarity on empty lists (Priority: P1)

As a first-time admin, I want to immediately understand what each list page represents when it has no data yet, and what my next best action is.

Why this priority: This is the first impression for new tenants/workspaces and for demos.

Independent Test: For each in-scope list page, with zero records, the page renders a complete empty state (icon + heading + description + one primary action).

Acceptance Scenarios:

1. Given I open an in-scope list page with no records, When the table renders, Then I see an icon, heading, description, and a single primary action.
2. Given I click the primary empty-state action, When I have the required permission, Then I am taken to the intended next step (or the intended operation is queued) without errors.

---

User Story 2 - Enterprise-grade consistency during evaluation (Priority: P2)

As a product evaluator, I want empty pages to feel intentional and guided, with consistent hierarchy and tone.

Why this priority: In low-data environments, evaluators spend disproportionate time on empty states.

Independent Test: Visual and UI assertions confirm consistent presence and ordering of empty-state elements across all in-scope pages.

Acceptance Scenarios:

1. Given I visit each in-scope list page with no records, When I compare the empty states, Then they share consistent structure and enterprise-appropriate wording (no scaffold-like presentation).

---

User Story 3 - Permission-aware guidance (Priority: P3)

As a workspace/tenant member without a required capability, I want to understand what I’m missing without the UI leaking access outside my membership scope.

Why this priority: Capability-aware UX reduces support load and aligns with RBAC-UX.

Independent Test: With membership but missing capability, the empty-state action is not actionable and explains why; server-side authorization remains enforced.

Acceptance Scenarios:

1. Given I am a valid member but lack the capability for the primary action, When I view the empty page, Then the CTA is disabled (or hidden where that’s the existing pattern) and communicates the missing permission.
2. Given I am not entitled to the workspace/tenant scope, When I attempt to access the list page, Then the app responds as not found (404 semantics).

Edge Cases

• Empty state must still render correctly in dark mode and light mode.
• Empty state must behave correctly when the tenant context is missing/invalid (records are not shown and the page does not leak data).
• Alert Deliveries list can be empty even when alerts are configured (e.g., no alerts fired yet); copy must set that expectation.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no new external integrations and no new background work. It only adjusts how existing list pages communicate “no records” states and which single next-step action is presented.

Constitution alignment (OPS-UX): This feature MUST NOT change operation UX semantics. Where an empty-state action already queues an operation (e.g., sync), it continues to follow the existing 3-surface feedback contract and uses the canonical operation UX presenter.

Constitution alignment (RBAC-UX): This feature MUST NOT relax authorization. It reuses existing capability gating and server-side authorization. Membership remains deny-as-not-found (404 semantics); missing capability remains 403 on execution.

Constitution alignment (Filament Action Surfaces): This feature modifies list empty states and therefore MUST satisfy the Action Surface Contract for the “ListEmptyState” slot for each in-scope resource.

Constitution alignment (UX-001 — Layout & Information Architecture): Each in-scope list page’s empty state must have a specific title, an explanation, and exactly 1 CTA.

Functional Requirements

• FR-001: Each in-scope primary list page MUST render a complete empty state when there are zero records.
• FR-002: Each empty state MUST include: icon, heading, description, and exactly one primary action.
• FR-003: Empty-state copy MUST be contextual to the module and explain both (a) why it’s empty and (b) the next best action.
• FR-004: Empty-state primary actions MUST remain capability-aware and MUST respect existing UI enforcement rules.
• FR-004a: The feature MUST preserve each resource’s existing CTA visibility model for capability enforcement rather than forcing all empty-state actions into a single visible-disabled or hidden-only pattern.
• FR-004b: When an empty-state CTA is shown disabled for a valid member, it MUST explain the missing permission using the resource’s existing helper text or tooltip pattern.
• FR-005: Empty-state rendering MUST remain correct in both light and dark mode.
• FR-006: Empty-state configuration MUST be defined in a single, consistent place per list page (to prevent drift and scaffold-like inconsistencies).
• FR-006a: Where Filament supports it, empty-state heading, description, icon, and action MUST be defined in the resource table() configuration.
• FR-006b: Page-level empty-state helpers MAY be used only when technically required, and MUST NOT split responsibility in a way that causes drift between heading/description/icon/action definitions.
• FR-007: Out-of-scope resources MUST remain unchanged, including: Finding, Entra Group, Policy Version, Operation Run.
• FR-008: The Alert Deliveries empty state MUST use a single navigational CTA labeled “View alert rules” to direct operators to the configuration surface most likely to explain or resolve an empty history.
• FR-008a: Alert Deliveries is the sole explicit UX-001 relocation exemption for this feature: the View alert rules CTA appears only in the empty state and MUST NOT persist as a table-header action once deliveries exist, because the surface remains intentionally read-only and header-action free.

Module-specific empty-state copy (baseline direction)

• Policies: “No policies synced yet. Sync your first tenant to see Intune policies here.”
• Backup Sets: “No backup sets. Create a backup set to start protecting your configurations.”
• Restore Runs: “No restore runs. Start a restoration from a backup set.”
• Backup Schedules: “No schedules configured. Set up automated backups.”
• Workspaces: “No workspaces. Create your first workspace.”
• Alert Deliveries: “No alert deliveries. Deliveries appear automatically when alert rules fire.”

Clarified CTA direction

• Alert Deliveries: use a single CTA labeled “View alert rules”.

UI Action Matrix (mandatory when Filament is changed)

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
Policy list	Admin UI — Policies list page	“Sync from Intune”	View action	View + “More” (as-is)	As-is	“Sync from Intune”	As-is	N/A (read-only details)	No	CTA continues to queue the existing sync operation; no change to operation UX semantics.
Backup Sets list	Admin UI — Backup Sets list page	“Create” (existing behavior)	View action	View + “More”	Yes	“Create backup set”	As-is	Create/Edit as-is	Yes (existing audit logger)	Empty state becomes contextual and guided; CTA remains capability gated.
Restore Runs list	Admin UI — Restore Runs list page	“Create” (existing behavior)	As-is	As-is	Yes	“New restore run”	As-is	Create wizard as-is	Yes (existing audit logger)	Empty state becomes contextual and guided; CTA remains capability gated.
Backup Schedules list	Admin UI — Backup Schedules list page	“New backup schedule” (existing behavior)	Clickable row	View/Edit as-is	Yes	“New backup schedule”	Edit page header as-is	Save/Cancel as-is	No	CTA remains capability-aware; disabled state explains missing permission.
Workspaces list	Admin UI — Workspaces list page	“New workspace” (existing behavior)	View action	View/Edit as-is	No	“New workspace”	As-is	Save/Cancel as-is	No	Workspace membership isolation remains deny-as-not-found.
Alert Deliveries list	Monitoring — Alert Deliveries list page	None (read-only)	Clickable row	None	None	“View alert rules” (navigation)	View page (read-only)	N/A	No	Adds guided empty state despite read-only list; CTA is a next-step navigation to alert rule configuration, not a mutation. Explicit UX-001 exemption: this CTA does not relocate to the header when records exist.

RBAC clarification

• Preserve each resource’s current capability-aware CTA behavior (disabled vs hidden) rather than standardizing all empty-state actions to one pattern.

Placement clarification

• Prefer resource table() definitions for empty-state heading, description, icon, and action; use page helpers only when technically required.

Visual QA evidence clarification

• Screenshot and dark-mode visual QA evidence for affected resources must be attached to the PR or review record, not committed into the repository.

Explicit exemptions

• Alert Deliveries header-action exemption: Alert Deliveries remains a read-only monitoring history surface with no persistent header action. Its single CTA (View alert rules) exists only while the list is empty. Once deliveries exist, the CTA does not relocate to the header; this is an explicit UX-001 exemption for this feature and must remain documented in the PR or review.

Acceptance Criteria / Definition of Done

1. All in-scope resources render a full empty state when the table has no records.
2. Each empty state includes icon, heading, description, and exactly one primary CTA.
3. Empty-state actions preserve existing RBAC/UI-enforcement behavior.
4. Visual review confirms centered, intentional hierarchy consistent with the baseline reference pattern.
5. Dark mode renders correctly for every affected list page.
6. Populated-table behavior remains unchanged.
7. Screenshot or visual QA evidence for all affected resources is attached to the PR or review artifact set, rather than committed to the repository.

Testing Requirements

• Feature/UI test per in-scope resource for empty table rendering.
• Feature/UI test coverage for each in-scope CTA outcome so empty-state actions either navigate to the intended next step or queue the intended existing operation.
• Permission test coverage to ensure CTA visibility or disabled state remains aligned with existing resource behavior.
• Manual visual verification in light and dark mode for every affected list page.
• Automated regression coverage for representative populated-table behavior, including CTA relocation for create-capable surfaces and the documented no-header-action exemption for Alert Deliveries.
• Smoke test confirming populated resources still render their standard tables and existing actions.
• PR/review attachment checklist confirming screenshots or equivalent visual QA evidence were captured for all affected resources.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 100% of in-scope list pages display icon + heading + description + 1 CTA when empty.
• SC-002: In a first-run demo with no records, an evaluator can correctly identify the purpose and next action on each in-scope page without guidance.
• SC-003: Users without capability can still understand the required permission from the disabled/hidden state messaging, without any cross-scope leakage.
• SC-004: No regressions: populated tables continue to render their existing columns, actions, and behaviors unchanged.