zarinpal-analytics-frontend/AGENTS.md

Frontend Agent Operating Contract

Phase gate

This repository is authorized for SDD Phase 4 implementation as of 2026-08-20. Follow tasks/todo.md in dependency order and keep the approved dashboard, UX, design, API, and deployment contracts authoritative. New capabilities or contract changes still require specification and approval before implementation.

For frontend work, invoke and follow sveltekit-svelte5-tailwind-skill before editing. Use the skill's indexed research workflow and read only the relevant sections. Use persian-writing for user-facing Persian copy, and apply the accessibility and interaction rules in DESIGN.md.

Stack contract after approval

• SvelteKit 2, Svelte 5 runes, strict TypeScript, Tailwind CSS v4 through the Vite plugin.
• Prefer a statically built/client-rendered authenticated panel served by Nginx. No SEO/SSR requirement is assumed. Any move to a Node adapter or SvelteKit server endpoints requires an ADR because the Go service is the backend authority.
• Import global Tailwind/design tokens once from the root layout. Use complete utility class names; do not generate class names dynamically.
• Organize by route flow and feature: reusable primitives, layout components, feature components, typed API client, formatting utilities, and tests.
• Keep secrets and authentication authority out of the browser. The frontend consumes server sessions through secure cookies and never persists credentials or sensitive payloads in local storage.

UI rules

• The interface is Persian-first and RTL; mixed numeric/technical values must set direction deliberately.
• Follow DESIGN.md. Do not invent new colors, spacing, radii, shadows, chart semantics, or motion without updating its changelog.
• Use semantic HTML, visible focus, keyboard-complete interactions, proper labels, announced validation/status messages, and minimum 44×44 px touch targets.
• Use Intl for dates/numbers and keep the displayed calendar, timezone, currency unit, and digit style explicit.
• Every analytics card/chart includes its time window, unit, metric definition/help, loading, empty, stale, and error states.
• Respect prefers-reduced-motion; never use transition: all. Motion is functional and restrained.

Quality and Git

• Use atomic Conventional/Commitizen commits.
• Track specs, design tokens, component contracts, tests, fixtures that contain no sensitive source data, and visual-regression baselines.
• API contracts are generated/shared through an approved machine-readable interface rather than duplicated ad hoc types.
• Required verification after implementation includes formatting, lint, svelte-check, unit/component tests, Playwright critical flows, production build, responsive/RTL checks, accessibility checks, and reduced-motion checks.