From 6ff59e06ab69423d8107bd9fb3a2dfd24dfe01fa Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 12:36:33 +0330 Subject: [PATCH] docs: establish SvelteKit repository rules --- .gitignore | 12 ++++++++++++ AGENT.md | 4 ++++ AGENTS.md | 32 ++++++++++++++++++++++++++++++++ README.md | 10 ++++++++++ 4 files changed, 58 insertions(+) create mode 100644 .gitignore create mode 100644 AGENT.md create mode 100644 AGENTS.md create mode 100644 README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..01e1762 --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +node_modules/ +.svelte-kit/ +/build/ +/dist/ +/coverage/ +.env +.env.* +!.env.example +*.log +.idea/ +.vscode/ + diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..e1154f0 --- /dev/null +++ b/AGENT.md @@ -0,0 +1,4 @@ +# Compatibility Pointer + +The canonical agent instructions are in [`AGENTS.md`](AGENTS.md). This file exists for compatibility only. + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..669861d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,32 @@ +# Frontend Agent Operating Contract + +## Phase gate + +This repository is in specification mode. Do not scaffold SvelteKit, install packages, or implement UI until the dashboard capability spec is explicitly approved. + +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. + diff --git a/README.md b/README.md new file mode 100644 index 0000000..f699e20 --- /dev/null +++ b/README.md @@ -0,0 +1,10 @@ +# ZarinPal Merchant Analytics — Frontend + +Persian RTL merchant analytics panel built with SvelteKit 2, Svelte 5, strict TypeScript, and Tailwind CSS v4. + +Current state: design/specification only. No frontend scaffold or runtime code has been approved yet. + +- [`DESIGN.md`](DESIGN.md): visual language, interaction rules, responsive behavior, and current design-system state. +- [`docs/DASHBOARD-SPEC.md`](docs/DASHBOARD-SPEC.md): draft product/UI requirements and acceptance criteria. +- [`AGENTS.md`](AGENTS.md): durable rules for future coding agents and contributors. +