starcoach-hackathon/zarinpal-analytics-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define seasonal reporting periods

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 13:38:23 +03:30
parent 70c0d9a4f2
commit 9a26a51eab
2 changed files with 5 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
DESIGN.md
View File

@@ -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. |