28 KiB
name, description, colors, typography, rounded, spacing, components
| name | description | colors | typography | rounded | spacing | components | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ZarinPal Merchant Analytics | Calm Persian-first merchant intelligence in a crisp, dense financial workspace. |
|
|
|
|
|
Design System: ZarinPal Merchant Analytics
Overview
Creative North Star: "The Calm Merchant Control Room"
This is a Persian-first merchant workspace built for repeated operational scanning. It feels calm rather than promotional: compact controls, exact figures, plain-language explanations, and crisp bordered surfaces let a merchant understand recent performance before drilling into transactions, payment attempts, fees, or peer context.
The world is recognizably ZarinPal through its wordmark, action blue, small yellow brand accent, right-to-left shell, and familiar right-side navigation. Density is deliberate but never cramped. The first viewport establishes scope in the fixed top bar and physical-right sidebar, then leads with a page heading, period control, KPI row, and payment-history chart. Motion is limited to state feedback, shell transitions, and the initial chart trace.
Key Characteristics:
- Persian-first RTL structure with Iran Yekan X FaNum and tabular merchant-facing numerals.
- Fixed 56px top bar, physical-right desktop sidebar, and mobile terminal selector in the navbar.
- Low-radius white or near-black financial surfaces separated primarily by 1px borders.
- ZarinPal blue reserved for actions, selection, navigation, chart emphasis, and focus.
- Semantic success, warning, and danger color always accompanied by words, icons, or both.
- Encouraging, factual summaries that move from recent performance to inspectable evidence.
Approved baseline provenance
The approved Persian-first baseline remains authoritative where the shipped artifact confirms it: the licensed font and license file stay tracked; light and dark themes remain semantic variants; values use Persian digits and Rial; merchant dates use the Jalali calendar and Asia/Tehran; RTL, bidi isolation, WCAG 2.2 AA, keyboard operation, reduced motion, safe peer comparisons, and traceable metrics remain binding. The artifact now resolves provisional visual guidance into the concrete tokens and component rules recorded here.
| Version | Date | Decision |
|---|---|---|
| 0.11.1 | 2026-08-21 | Hardened narrow-screen shell, calendar, and chart behavior: the navbar wordmark and duplicate drawer terminal selector are hidden on mobile, exact-period fields cannot overlap, payment charts keep their readable width with horizontal scrolling, and the growth teaser gains an action-blue emphasis with a restrained reduced-motion-safe pulse. |
| 0.11.0 | 2026-08-21 | Added the feature-gated AI growth analyst: a cache-first 90-day forecast view with count/amount modes, P10–P90 uncertainty band, keyboard and tabular alternatives, evidence-linked Persian campaign guidance, preserved-content refresh states, and restrained semantic opportunity/risk styling. |
| 0.10.0 | 2026-08-20 | Reframed retry guidance around the share of failed payment paths retried, including an explicit zero state; made payment-flow bars proportional to counts; and removed single-day hover styling from whole-week selection. |
| 0.9.3 | 2026-08-20 | Replaced stacked field focus outlines with one narrow semantic-blue border across text fields, textareas, native selects, and custom select triggers; other keyboard targets retain a subtle 1px outline. |
| 0.9.2 | 2026-08-20 | Pinned the initialization skeleton sidebar to the physical right and reserved matching right-side content space so loading and loaded shells share the same geometry. |
| 0.9.1 | 2026-08-20 | Distributed the desktop period-type group and exact-period control across the available filter-bar width while preserving the compact mobile sheet layout. |
| 0.9.0 | 2026-08-20 | Added labeled X/Y axes and Persian ticks to the payment-history chart, and made the fee-share donut fluidly fill its dedicated visual column on larger viewports. |
| 0.8.0 | 2026-08-20 | Increased light-theme skeleton contrast, constrained and animated chart tooltips, made default period choices explicitly applicable, hid collapsed-sidebar labels, and strengthened the separation between period type and exact-period controls. |
| 0.7.0 | 2026-08-20 | Made period changes confirm-on-selection, moved narrow-screen filters into a bottom sheet, enlarged collapsed navigation targets, simplified focus rings, and promoted the fee-share chart into a dedicated visual column. |
| 0.6.0 | 2026-08-20 | Added full-span Jalali period selection, unified transaction status/amount controls, persistent skeleton states, custom RTL dropdowns, semantic peer/retry tones, and fee-share visualization; tightened the narrow navbar and 600px KPI breakpoint. |
| 0.5.0 | 2026-08-20 | Reconciled the approved baseline with the shipped routed frontend and desktop, mobile, and 639px review captures; converted the file to canonical DESIGN.md format and added the design sidecar. |
| 0.4.0 | 2026-08-20 | Adopted the current ZarinPal panel as the closer interaction reference: top wordmark bar, 256/72px collapsible right sidebar, 8px data surfaces, routed sections, URL-backed period and terminal filters, payment-history chart, transaction table, attempt history, formula help, and supportive insights. |
| 0.3.3 | 2026-08-20 | Replaced merchant/cohort revision freshness language with the approved immutable completed-import dataset snapshot. |
| 0.3.2 | 2026-08-20 | Made the licensed Iran Yekan X FaNum variable WOFF2 and its required license file Git-tracked frontend assets. |
| 0.3.1 | 2026-08-20 | Verified the purchased Iran Yekan X Professional FaNum variable assets and added merchant-owned detail CSV export as an MVP contract. |
| 0.3.0 | 2026-08-20 | Approved Iran Yekan X Professional FaNum, Persian digits, Rial-only values, first-class light/dark themes, and the deterministic insight threshold. |
| 0.2.4 | 2026-08-20 | Fixed the default period, comparison fallback, KPI priority, read-only drill-down scope, and accurate NoAttempt/InBank stage language. |
| 0.2.3 | 2026-08-20 | Kept authentication UX intentionally demo-sized with a clean replacement boundary for ZarinPal SSO. |
| 0.2.2 | 2026-08-20 | Defined backend-owned session UX and generic accessible expiry/revocation handling. |
| 0.2.1 | 2026-08-20 | Defined peer cards as an equal-per-merchant median plus direction-aware percentile. |
| 0.2.0 | 2026-08-20 | Corrected payment lifecycle semantics: Paid and Verified are bank-payment successes, Paid remains unverified, and session fees are real Rial amounts. |
| 0.1.9 | 2026-08-20 | Added rate-limit UX, SSE heartbeat/recovery, replay, and failed-section-only retry. |
| 0.1.8 | 2026-08-20 | Fixed the parallel analytics section identifiers, cache, idempotent start/SSE flow, and section timeout/retry behavior. |
| 0.1.7 | 2026-08-20 | Defined partial, parallel section delivery through authenticated SSE. |
| 0.1.6 | 2026-08-20 | Replaced time-based analytics freshness with lazy calculation and defined Saturday–Friday weeks. |
| 0.1.5 | 2026-08-20 | Limited period controls to daily, weekly, Jalali-month, and Persian-season views. |
| 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 UTC API instants. |
| 0.1.0 | 2026-08-20 | Established the ZarinPal-inspired RTL foundation, responsive shell, core components, accessibility, chart, and motion rules. |
Colors
The palette is a neutral financial canvas with one decisive blue voice, a very small yellow identity accent, and restrained semantic color.
Primary
- ZarinPal Action Blue: Drives selected range controls, active navigation, interactive chart marks, links, and primary focus. Its night-theme companion is brighter so the same roles stay legible on near-black surfaces.
- Action Tint: Supports active navigation and lightly emphasized information without turning whole cards blue.
Secondary
- ZarinPal Yellow: Appears in the supplied wordmark and text selection. It is an identity spark, not a general dashboard accent or text color.
Tertiary
- Success: Successful payments and ready states.
- Warning: Incomplete verification, suppression, or caution.
- Danger: Errors, failed states, and destructive meaning.
Neutral
- Workspace: A cool, near-white light canvas and a near-black night canvas frame the application.
- Surface: Cards, navbar, sidebar, menus, and overlays sit one tonal step above the workspace.
- Nested Surface: Table headers, secondary controls, progress tracks, and quiet hover states use the muted neutral layer.
- Ink and Muted Ink: Strong figures and headings use high-contrast ink; explanations, metadata, and control labels use muted ink.
- Border: A cool 1px line is the default separator between data surfaces and within tables.
Named Rules
The One Blue Voice Rule. Blue signals an action, current scope, active navigation, focus, or the primary data series; it does not wash large passive regions.
The Meaning Needs Language Rule. Success, warning, and danger color reinforce a visible label, icon, or explanation and never carry status alone.
Typography
Display Font: Iran Yekan X Professional FaNum variable (IRANYekanX), with Tahoma and sans-serif fallbacks.
Body Font: Iran Yekan X Professional FaNum variable (IRANYekanX), with Tahoma and sans-serif fallbacks.
Character: One Persian UI family keeps the workspace cohesive and highly legible. Weight, size, tabular figures, and spacing create hierarchy; ornamental display typography is outside this product world.
Hierarchy
- Page Heading (800, 20px; 24px from 640px, 1.4): Routed page identity at the top of the workspace.
- Section Heading (700, 20px; 24px from 640px, 1.5): Major analytics modules and explanatory groups.
- Metric (800, 24px, 1.25): KPI values, amounts, rates, and transaction totals; use tabular numerals.
- Body (400, 15px, 1.8): Default interface copy and longer Persian explanations.
- Supporting (400, 14px, usually 1.75): Descriptions, filters, table content, and insight summaries.
- Label (500–600, 12px, 1.5): Metadata, compact controls, badges, terminal context, and chart annotations; never go below 11px, which is reserved for the two-line terminal identity in the desktop sidebar.
Named Rules
The Persian Measure Rule. Merchant-facing amounts, counts, percentages, dates, and chart values use Persian digits; technical identifiers remain canonical Latin inside isolated left-to-right spans.
The Weight Before Scale Rule. The dense workspace creates hierarchy first with 500, 700, and 800 weights, then with a compact 12/14/15/20/24px size ladder.
Layout
The application is a bounded RTL shell. A fixed 56px top navbar spans the viewport. At 768px and wider, a physical-right sidebar is 256px expanded and 72px collapsed; its top card holds merchant identity and terminal selection. The content column is centered at a maximum of 1220px with 16px gutters, increasing to 24px at 640px and 32px at 1024px.
The overview begins with a compact title block and full-width range selector. KPI cards form two columns from 600px and four columns from 1024px; the payment-history chart follows as the dominant full-width surface. Deeper pages reuse the same header, filters, bounded cards, and horizontally scrollable tables.
Below 768px, the sidebar yields to the navbar. Terminal selection moves into the top bar beside the wordmark and theme utility, while content uses 16px gutters. The account initial is intentionally hidden below 640px so terminal scope and navigation never overflow. KPI cards remain stacked on phone widths and become a compact 2×2 set from 600px, preserving scan order while bringing the payment-history chart into view sooner.
The Scope Before Evidence Rule. Terminal and period scope must be visible before KPIs, charts, tables, or attempt history; desktop terminal scope belongs in the right sidebar and narrow-screen terminal scope belongs in the navbar.
Elevation & Depth
The system is flat by default. Workspace, card, nested surface, and border tones establish hierarchy; the repeated low shadow is only a small reinforcement on cards and controls. The fixed top bar uses an even quieter separator shadow, while tooltips, sheets, and dialogs can use stronger overlay elevation.
Shadow Vocabulary
- Surface Low (0 1px 2px 0 rgb(0 0 0 / 0.05)): KPI cards, charts, filter bars, and repeated dashboard containers.
- Navbar Hairline (0 1px 2px rgba(0, 0, 0, 0.03)): Fixed top bar only.
- Overlay High (0 20px 25px -5px rgb(0 0 0 / 0.10), 0 8px 10px -6px rgb(0 0 0 / 0.10)): Floating chart tooltip and modal-level content only.
Named Rules
The Border Carries Structure Rule. Use the 1px border and tonal layers for resting structure; reserve conspicuous shadows for content that actually floats above the shell.
Shapes
The form language is low-radius and precise. Data cards, filter bars, inputs, selects, and standard buttons resolve around 8px; dense internal controls and active navigation use 6–7px. Status badges may be pills because their silhouette communicates compact state. Avatars and small identity marks may be circular. Large soft containers are limited to modal-scale overlays or empty states and must not migrate into the dense dashboard.
The Data Surface Radius Rule. Repeated financial surfaces use 8px corners and a visible border; rounding must not make tables, KPIs, or filters feel like marketing cards.
Components
Buttons
- Shape: Compact, bordered or filled, with 6–8px corners and 32–36px desktop height; touch layouts raise interactive targets to at least 44px.
- Primary: Action blue with white content in light mode and dark ink on the brighter night action blue.
- Hover / Focus: Hover changes tone; active state moves down by 1px where the action is press-like. Keyboard focus uses a restrained 1px semantic blue ring plus the border shift. State transitions stay around 160ms.
- Ghost: Transparent at rest, muted-neutral on hover, used for inactive range choices and utility icons.
Chips
- Style: Compact 20px badges use 12px medium text. Semantic badges may be pill-shaped; date and percentile chips use the tighter control radius.
- State: Selected filters use filled blue plus aria-pressed; ready, warning, and failure labels pair color with explicit text.
Cards / Containers
- Corner Style: Dense 8px corners.
- Background: Theme surface over theme workspace; lightly emphasized insight cards may use an action or semantic tint.
- Shadow Strategy: Surface Low only, with border/ring structure always present.
- Border: One cool neutral pixel; semantic borders are translucent accents on error or insight surfaces.
- Internal Padding: 20px is the desktop KPI rhythm and contracts to 16px on phones; 24px supports explanatory cards, and charts may use 12px horizontally on narrow screens.
Inputs / Fields
- Style: Transparent or workspace-toned field, 1px input border, 6–8px radius, 32–36px desktop height, 44px touch height, and compact 12–14px text. Terminal and status selects use the same RTL popover primitive rather than the browser-native menu.
- Focus: Text fields, textareas, native selects, and custom select triggers use one narrow semantic-blue border without a second outer ring. Other keyboard-focusable controls use a restrained 1px outline.
- Error / Disabled: Error uses danger border plus ring; disabled fields reduce opacity and preserve legible text.
Navigation
- Desktop: The fixed right sidebar is white/near-black with 44px task rows, 19px outline icons, 13px labels, and an action-tint active background with blue content.
- Mobile: The fixed top bar retains the wordmark, terminal selector, theme action, and menu trigger. The account initial appears from 640px and is intentionally omitted on narrower phones.
- State: Current routes use a background plus blue text and remain identified with aria-current or equivalent active state.
KPI Card
The signature KPI card pairs a muted label and optional formula help with a semantic 20px outline icon, a 24px extra-bold tabular value, and one short 12px explanatory line. It uses 16px padding on phones and 20px above that, and may lift 2px over 200ms on hover without changing its information hierarchy.
Reporting Scope Filter
Daily, Saturday–Friday weekly, Jalali-month, and Persian-season controls share one URL-backed bar. Clicking a period type first opens the exact-period picker; the URL and backend request change only after a concrete period is chosen. The compact RTL popover provides a four-digit Jalali year input, month navigation plus calendar grid for day/week, whole-week hover and selection, and named month/season choices. Transaction status and a two-thumb RTL amount range sit to the physical right of the calendar control after a divider. Below 768px, the full set moves into a bottom sheet. Backend-offered complete periods are the selectable authority.
Loading State
Scope changes immediately replace data-dependent cards, tables, detail panels, and charts with geometry-matched skeletons. The title, selected scope, and navigation stay visible; no routed data surface collapses into an empty page while the API is working.
Payment-History Chart
The signature chart is a blue line with outlined points, a low-opacity blue area, dashed neutral gridlines, labeled X/Y axes, Persian date ticks, and successful-payment count ticks. It follows a written title and reporting-period chip, provides focusable points with spoken values, and animates its initial trace once over 900ms while reduced-motion collapses the effect. Point tooltips use a short scale/fade transition, flip above or below according to vertical room, and clamp their center so the surface never leaves the chart wrapper.
Payment Performance
Retry engagement is the share of failed payment paths that customers tried again, using final failures plus recovered failed paths as the opportunity denominator. When opportunities exist and none are retried, the merchant sees ۰٪, not an unavailable state. The adaptive guidance depends only on this percentage. Flow bars use the same total-session scale, so equal counts always render at equal widths.
Transaction Table
The table stays inside a bordered 8px surface, receives its compact filters from the shared page bar, uses aligned 14px rows and 12px identifiers/status, and exposes semantic detail links with a pointer and neutral row hover. Verified badges are green; Paid remains neutral gray. Narrow viewports may scroll the table horizontally after surrounding filters and summaries have reflowed.
Fee Share and Comparative Progress
The fee page gives the circular share chart a large physical-right column while three numeric KPI cards stack in the adjacent column. Peer progress bars move from rose through amber and sky to emerald as the direction-adjusted percentile improves. Retry guidance uses amber, sky, or emerald surfaces and changes its supportive sentence at tested recovery/sample thresholds.
Do's and Don'ts
Do:
- Do keep the terminal selector in the physical-right desktop sidebar and in the narrow-screen navbar.
- Do lead with the selected period, four ordered KPIs, a plain-language takeaway, and then inspectable chart or table evidence.
- Do use action blue for the current scope, primary series, focus, and actionable controls.
- Do keep cards at 8px with a 1px border and use 16px KPI padding on phones, increasing to 20px from 640px.
- Do preserve Persian digits, Rial units, Jalali dates, RTL flow, and left-to-right isolation for technical identifiers.
- Do provide text, icons, focus states, and accessible alternatives anywhere color or a chart carries meaning.
Don't:
- Don't turn yellow into a broad dashboard fill or use it for body text on light surfaces.
- Don't use pill geometry for cards, tables, inputs, or ordinary navigation rows.
- Don't add decorative gradients, oversized hero type, or marketing-page whitespace to authenticated analytics routes.
- Don't use shadow as the primary boundary between resting financial surfaces.
- Don't animate the page as a spectacle; keep motion to state feedback, the shell, overlays, and the chart trace, and honor reduced motion.
- Don't hide status, scope, units, formulas, or important chart values behind color or pointer-only interaction.