support_frontend/specs/002-reporting-dashboards-ui/checklists/requirements.md

Specification Quality Checklist: Reporting and Analytics Dashboards UI

Purpose: Validate specification completeness and quality before proceeding to planning Created: 2026-09-09 Feature: spec.md

Content Quality

• No implementation details (languages, frameworks, APIs)
• Focused on user value and business needs
• Written for non-technical stakeholders
• All mandatory sections completed

Requirement Completeness

• No [NEEDS CLARIFICATION] markers remain
• Requirements are testable and unambiguous
• Success criteria are measurable
• Success criteria are technology-agnostic (no implementation details)
• All acceptance scenarios are defined
• Edge cases are identified
• Scope is clearly bounded
• Dependencies and assumptions identified

Feature Readiness

• All functional requirements have clear acceptance criteria
• User scenarios cover primary flows
• Feature meets measurable outcomes defined in Success Criteria
• No implementation details leak into specification

Notes

• Backend counterpart (supporthub-api's 015-reporting-dashboards) is already complete and committed — this feature is presentation-only, per the same backend-first pattern already used for every prior feature spanning both repos this session.
• The user asked explicitly for "production-level design" — this feature's plan.md accordingly applies this project's dataviz skill methodology (form selection before color, status colors reserved for status-flavored distributions, sequential single-hue for magnitude rankings, validated against both light and dark mode) rather than an ad hoc visual treatment.
• All items pass; no revision iterations were needed. No [NEEDS CLARIFICATION] markers were required.

Implementation-time findings

• dataviz palette validation caught a real dark-mode gap in this app's existing status colors. Running scripts/validate_palette.js against the Badge component's own emerald-500/amber-500/--destructive convention (chosen over the raw --warning/--success CSS tokens, which fail contrast outright in light mode) showed the convention passes in light mode but fails two checks in dark mode: warning/success CVD separation is 5.5, under the 6 floor, and destructive's dark value (#7f1d1d) has a contrast ratio of only 1.74 against the dark surface. Rather than reworking this app's established status-color tokens (out of this feature's scope), every new status-flavored component (StatusDistribution) applies the skill's own prescribed mitigation for a borderline palette: identity never rides on color alone — each segment pairs its bar color with a distinct icon shape (CheckCircle2 / AlertTriangle / XCircle) and a visible text label, in both the legend and the segment itself. This satisfies the CVD floor-band's secondary-encoding requirement and the contrast WARN's "visible labels required" mitigation.
• A real backend bug was found and fixed via manual verification against real seeded data, not by any automated test: ManagementRepository.countEverEscalatedToHuman and ProductReportRepository.countEverEscalatedToHuman (015-reporting-dashboards) checked a list of terminal statuses that, per ticket-state-machine.ts's own transition table, is reachable from BOTH the AI-resolved path and the human-escalation path once they converge on shared terminal statuses (RESOLUTION_PENDING_CUSTOMER/RESOLVED/CLOSED/REOPENED) — so every AI-resolved ticket was being double-counted as human-escalated too (confirmed live: 34/34 tickets, 100%, against real dev data). Fixed by keying off assignments: { some: {} } instead, since orchestrationService.handleHumanEscalation is the only code path that ever creates an Assignment row. This is why this feature's own frontend verification session is the reason 015's own dashboards now report correct figures.
• The Tabs primitive's mobile layout had a real overflow bug, found only by taking an actual screenshot (not just an accessibility-tree read) at a 390px viewport: TabsList centered its six tabs with no scroll affordance, so the active tab was clipped off-screen on both edges instead of being scrollable into view. Fixed in components/ui/tabs.tsx by making the list horizontally scrollable on narrow viewports (overflow-x-auto, left-aligned, shrink-0 triggers) while keeping the existing centered/inline layout at sm: and above.
• Per-agent workload in the Support dashboard displays the raw agentId (no name-lookup endpoint exists yet) — accepted as data-model.md's own documented fallback rather than adding a new endpoint or an N+1 lookup out of this feature's scope.
• The full Playwright E2E suite, run serially against the real dev backend, intermittently trips 013-auth-hardening's real login rate limiter (LOGIN_RATE_LIMIT_MAX_ATTEMPTS=5 per LOGIN_RATE_LIMIT_WINDOW_SECONDS=300) because every spec file shares the same admin@supporthub.internal test account and each does its own real login. This is confirmed pre-existing: the same failures occur running the suite with this feature's new reports-dashboards.spec.ts entirely excluded. This feature's own E2E spec passes 3/3 cleanly in isolation; the shared-account rate-limit interaction is a systemic property of the existing E2E suite design, not a regression introduced here.