From 70c0d9a4f23ad1ff90fe8752b571d0c0d8d0bb2b Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 13:26:51 +0330 Subject: [PATCH] docs: define suppressed benchmark state --- DESIGN.md | 5 +++-- docs/DASHBOARD-SPEC.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 1bbef57..a2128df 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,7 +1,7 @@ # Design System — ZarinPal Merchant Analytics - Status: Draft baseline for approval -- Version: 0.1.1 +- Version: 0.1.2 - Last updated: 2026-08-20 - Direction: Persian-first RTL @@ -105,7 +105,7 @@ Navigation labels should describe merchant tasks, not internal database concepts ## Data visualization - 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 eligible anonymized cohort. +- 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. - 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. @@ -142,6 +142,7 @@ Navigation labels should describe merchant tasks, not internal database concepts | Version | Date | Decision | |---|---|---| +| 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 0f4bf14..3e852c4 100644 --- a/docs/DASHBOARD-SPEC.md +++ b/docs/DASHBOARD-SPEC.md @@ -20,7 +20,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe 2. The app shell identifies the active merchant and offers logout. 3. Overview shows data freshness, selected period, primary outcomes, trend, and prioritized deterministic insights. 4. Payment performance supports success/failure/retry/timing analysis and traceable drill-downs. -5. Peer comparison exposes only eligible anonymized cohort aggregates and explains suppression/limitations. +5. Peer comparison excludes the active merchant and exposes only eligible anonymized cohort aggregates. It displays a value only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise it explains that there is not enough data. This never hides the merchant's own analytics. 6. Filters and pagination are reflected in the URL where sharing/reload is useful. 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`.