From 9a26a51eabecd787fb02b095829c1cf00a80c9a1 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 13:38:23 +0330 Subject: [PATCH] docs: define seasonal reporting periods --- DESIGN.md | 7 ++++--- docs/DASHBOARD-SPEC.md | 1 + 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index a2128df..5311b32 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,7 +1,7 @@ # Design System — ZarinPal Merchant Analytics - Status: Draft baseline for approval -- Version: 0.1.2 +- Version: 0.1.3 - Last updated: 2026-08-20 - Direction: Persian-first RTL @@ -98,7 +98,7 @@ Navigation labels should describe merchant tasks, not internal database concepts - **Chart card:** title, period/filter controls, concise takeaway, plot, legend, accessible tabular alternative, provenance link. - **Insight card:** deterministic finding, numeric evidence, suggested merchant action, confidence/limitation; AI-generated copy is visibly labeled later. - **Data table:** semantic headers, server pagination/sorting, row actions named for screen readers, responsive priority, empty/error states. -- **Filter bar:** URL-backed state, explicit apply/reset behavior, Persian date/time semantics. +- **Filter bar:** URL-backed state, explicit apply/reset behavior, and approved day, Jalali-month, Persian-season, and named holiday/event periods with unambiguous comparison baselines. - **Status badge:** text plus icon/shape; color reinforces but never carries meaning alone. - **Feedback:** inline field errors, page-level error boundary, skeleton only when layout is known, retry action for recoverable failures. @@ -106,7 +106,7 @@ Navigation labels should describe merchant tasks, not internal database concepts - Lead with a written takeaway and exact KPI; charts support the conclusion rather than decorate it. - Default comparisons: current period vs previous equivalent period and merchant vs an eligible anonymized cohort. Peer values appear only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise show a clear insufficient-data state. -- Always show unit, timezone/calendar, date window, sample size, freshness, and missing-data caveat where material. +- Always show unit, timezone/calendar, date or named-event window, comparison baseline, sample size, freshness, and missing-data caveat where material. - Success/failure colors remain semantic and consistent. Never use a rainbow categorical palette for ordered values. - Tooltips are keyboard reachable and not the sole location of important values. - Charts have a textual summary and downloadable/visible data table when practical. @@ -142,6 +142,7 @@ Navigation labels should describe merchant tasks, not internal database concepts | Version | Date | Decision | |---|---|---| +| 0.1.3 | 2026-08-20 | Added explicit Jalali-month, Persian-season, and named holiday/event reporting periods with visible baselines and evidence. | | 0.1.2 | 2026-08-20 | Added the insufficient-data state and visibility threshold for anonymized peer comparisons. | | 0.1.1 | 2026-08-20 | Fixed merchant-facing time presentation to the Jalali calendar in `Asia/Tehran`, with explicit UTC API instants. | | 0.1.0 | 2026-08-20 | Established ZarinPal-inspired RTL foundation from supplied public/panel screenshots; fixed SvelteKit/Svelte/TypeScript/Tailwind stack; defined responsive shell, core components, accessibility, chart, and motion rules. | diff --git a/docs/DASHBOARD-SPEC.md b/docs/DASHBOARD-SPEC.md index 3e852c4..84b8aee 100644 --- a/docs/DASHBOARD-SPEC.md +++ b/docs/DASHBOARD-SPEC.md @@ -25,6 +25,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe 7. Every screen implements loading, empty, partial-data, stale, unauthorized, forbidden, and recoverable-error behavior as applicable. 8. Responsive behavior and component contracts follow `DESIGN.md`. 9. Merchant-facing dates use the Jalali calendar in `Asia/Tehran`; API instants remain explicit ISO-8601 UTC and filtering sends unambiguous boundaries. +10. Approved reporting periods include day, Jalali month, Persian season, and named Iranian holiday/event windows. Every comparison states its exact period and baseline; one observed event period is not presented as recurring seasonality. ## Frontend architecture baseline