--- name: ZarinPal Merchant Analytics description: Calm Persian-first merchant intelligence in a crisp, dense financial workspace. colors: action-blue: '#0A33FF' action-blue-night: '#6F8DFF' action-tint-light: '#EEF1FF' action-tint-night: '#202950' brand-yellow: '#FFD400' workspace-light: '#F5F5F6' surface-light: '#FFFFFF' nested-light: '#F3F4F6' ink-light: '#18181B' muted-ink-light: '#71717A' border-light: '#E4E4E7' workspace-night: '#101012' surface-night: '#19191C' ink-night: '#FAFAFA' muted-ink-night: '#A1A1AA' border-night: '#3A3A3D' success-light: '#248061' warning-light: '#8A5300' danger-light: '#C93637' success-night: '#6FD6AE' warning-night: '#F3BE5B' danger-night: '#FF8A8B' typography: page-heading: fontFamily: 'IRANYekanX, Tahoma, sans-serif' fontSize: '1.25rem' fontWeight: 800 lineHeight: 1.4 letterSpacing: '-0.025em' section-heading: fontFamily: 'IRANYekanX, Tahoma, sans-serif' fontSize: '1.25rem' fontWeight: 700 lineHeight: 1.5 metric: fontFamily: 'IRANYekanX, Tahoma, sans-serif' fontSize: '1.5rem' fontWeight: 800 lineHeight: 1.25 fontFeature: 'tnum' body: fontFamily: 'IRANYekanX, Tahoma, sans-serif' fontSize: '0.9375rem' fontWeight: 400 lineHeight: 1.8 supporting: fontFamily: 'IRANYekanX, Tahoma, sans-serif' fontSize: '0.875rem' fontWeight: 400 lineHeight: 1.75 label: fontFamily: 'IRANYekanX, Tahoma, sans-serif' fontSize: '0.75rem' fontWeight: 500 lineHeight: 1.5 rounded: compact: '6px' control: '7px' surface: '8px' pill: '9999px' spacing: 1: '4px' 2: '8px' 3: '12px' 4: '16px' 5: '20px' 6: '24px' 8: '32px' components: button-primary: backgroundColor: '{colors.action-blue}' textColor: '{colors.surface-light}' typography: '{typography.label}' rounded: '{rounded.surface}' padding: '0 10px' height: '32px' button-ghost: backgroundColor: 'transparent' textColor: '{colors.ink-light}' typography: '{typography.label}' rounded: '{rounded.surface}' padding: '0 10px' height: '32px' card: backgroundColor: '{colors.surface-light}' textColor: '{colors.ink-light}' typography: '{typography.body}' rounded: '{rounded.surface}' padding: '20px' input: backgroundColor: 'transparent' textColor: '{colors.ink-light}' typography: '{typography.supporting}' rounded: '{rounded.surface}' padding: '4px 10px' height: '32px' nav-active: backgroundColor: '{colors.action-tint-light}' textColor: '{colors.action-blue}' typography: '{typography.supporting}' rounded: '{rounded.compact}' padding: '8px 12px' height: '44px' --- # 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.13.0 | 2026-08-22 | Replaced equal upcoming-event cards with an RTL shared-baseline priority histogram and ranked evidence cards. Three positive integer shares descend from physical right and total ۱۰۰٪; visible copy distinguishes planning priority from growth probability. Historical occasion evidence takes precedence over onboarding-profile signals, with explicit source and promote/prepare/caution labels. | | 0.12.0 | 2026-08-22 | Replaced the Transactions table with a period-scoped operational-health dashboard: four status KPIs, an absolute-count distribution chart, a 100% composition trend, keyboard inspection, and visible semantic data-table alternatives. Status colors are fixed to blue Paid/awaiting verification, emerald Verified/final, rose Failed, and amber Reversed. | | 0.11.1 | 2026-08-21 | Hardened narrow-screen shell, calendar, and chart behavior: the navbar uses the compact authentication-screen brand mark while the opened mobile drawer carries the full typographic wordmark and the only terminal selector, 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. The Transactions analytics page intentionally exposes only terminal and period scope; legacy status and amount query parameters do not affect it. Below 768px, period selection 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 Status Analytics The Transactions page contains no rows or drill-down links. Its primary chart uses four vertical absolute-count bars in the fixed order Paid, Verified, Failed, Reversed. Its secondary chart plots one line with focusable dots per status across the backend-provided time buckets. Paid means «پرداخت‌شده، در انتظار تأیید» and is blue; Verified means «تأیید نهایی» and is emerald; Failed is rose; Reversed is amber. These colors are stable in both themes and always appear with explicit status text. Every mark is keyboard-focusable, exposes count and percentage, honors reduced motion, and is backed by a visible expandable semantic table. Chart cards always show the selected-period badge, unit or denominator explanation, and explicit loading, error, and empty states. ### 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. ### Event Planning Priority The growth page ranks up to three upcoming occasions in one shared-baseline histogram. Rank 1 is the physical-right column in RTL; all available columns remain side by side on phones because their relative heights are the comparison. Column height maps literally to an integer planning-priority share, and the visible percentages total ۱۰۰٪. When only one or two candidates exist, a visible note names that limited set and the chart divides attention only among those events. A nearby clarification says these values allocate planning attention and are not growth probabilities. The histogram is the section's single visual signature: rank 1 uses the primary data color, while ranks 2 and 3 use progressively quieter mixtures of the same token and the nested surface. It uses no gradient, floating shadow, or decorative motion. Height changes may transition for 240ms and become immediate under reduced motion. Rank, title, percentage, total, and an ordered screen-reader description make the chart understandable without color or pointer interaction. Evidence cards stack beneath the compact chart on phones and form up to three physical-right-to-left columns from the medium breakpoint. Each card shows the event range, reason, explicit stance, and one source badge: «بر پایه تجربه شما» or «بر پایه شناخت کسب‌وکار». Historical cards show the previous occasion range, observation count, paid-session uplift, and amount uplift. Profile-grounded cards show onboarding-derived category, niche, or channel signals; if none are available, they say that only general profile context was used. Typed history-unavailable codes are translated into natural Persian. A visible warning identifies deterministic `PARTIAL` copy. Success, action, or warning accents reinforce the written promote, prepare, or caution stance and never replace it. ## 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. ### Competitive Position Board (0.14.0) The «جایگاه رقابتی» page uses a ranked, full-width board rather than a generic KPI grid. Cards sort from the highest merchant percentile to the lowest, show a restrained rank, exact Persian percentile, semantic status text, and a dual-marker rail: the merchant score and the fixed cohort median at ۵۰. Each card is a keyboard-accessible disclosure for its definition, direction, and interpretation. The page pairs the board with a sticky AI panel on desktop and places the AI panel first on mobile. Motion is limited to the rail fill and is removed under `prefers-reduced-motion`.