# راهنمای سبک — سوپردوپر مارکت

منطق طراحی سه صفحه‌ی اصلی، اصول مشترک و قواعدی که هنگام افزودن صفحه یا
کامپوننت جدید باید رعایت شوند.

---

## اصول مشترک

- **تایپوگرافی:** دو فونت متغیر. **وزیرمتن** (`--sp-font`) برای متن، رابط و
  اعداد؛ **رخ** (`--sp-font-display`) برای تیترها — همه‌ی `<h1>`–`<h6>` و
  عنوان‌های نام‌دار مثل `.sp-section-title` و `.sp-hero-title`. رخ لحن
  نمایشی‌تری دارد و تیترها را از متن جدا می‌کند. اندازه‌ی پایه `14px`،
  ارتفاع خط `1.75`. تیترهای هیرو با `clamp()` تعریف شده‌اند و بدون media
  query با عرض صفحه مقیاس می‌گیرند.
- **بافت:** اسلایدرها و بنرها یک لایه‌ی بافت برداری دارند (نقطه‌چین ۱۸px یا
  هاشور مورب) که با `color-mix()` از توکن‌های همان پالت رنگ می‌گیرد. کنتراست
  بافت بین ۷ تا ۹ درصد نگه داشته می‌شود — بافت، نه تزئین.
- **اعداد:** همیشه با ارقام فارسی و جداکننده‌ی هزارگان. در زمان build با
  `components.fa()` و در مرورگر با `fa()` / `toman()` از `superium.js`.
  هیچ عدد لاتینی نباید در متن رابط کاربری دیده شود.
- **قیمت:** واحد تومان. قیمت خط‌خورده فقط وقتی نمایش داده می‌شود که
  `discountRatio > 0` باشد.
- **ریتم عمودی:** فاصله‌ی بین بخش‌ها با `--sp-section-y`
  (`clamp(28px, 4vw, 56px)`).
- **حرکت:** منحنی `cubic-bezier(0.22, 1, 0.36, 1)` به‌عنوان easing استاندارد
  (`--sp-ease`) و مدت `0.25s` (`--sp-dur`). همه‌ی انیمیشن‌ها با
  `prefers-reduced-motion` خاموش می‌شوند.
- **عکس محصول:** همیشه روی زمینه‌ی سفید و مربعی، با `object-fit: contain`. در
  پالت تیره هم زمینه سفید می‌ماند تا بسته‌بندی خوانا بماند.
- **راست‌به‌چپ:** فقط ویژگی‌های منطقی. برای بررسی:
  ```bash
  grep -nE '\b(left|right)\s*:' assets/css/superium*.css
  ```
  خروجی باید خالی باشد.

---

## ۱ — تازه (Fresh) · گرم · `home-1-fresh.html`

- **پالت:** اصلی `#f2600c` · تاکید `#16a34a` · پس‌زمینه `#fdf7f1` (کرم)
- **معماری:** هیروی کلاژی. ستون متن در سمت راست، چهار کاشی دسته‌بندی در سمت چپ
  که یکی‌درمیان ۲۰ پیکسل پایین‌تر می‌نشینند تا بلوک به‌جای «شبکه» شبیه «کلاژ»
  باشد.
- **دسته‌بندی:** ریل افقی از قرص‌های گرد عکس‌دار — نزدیک‌ترین حالت به اپلیکیشن
  سوپرمارکت.
- **کالای منتخب:** ریل‌های افقی موضوعی («خنک شو!»، «تازه‌تر از تازه»، «قفسه
  تنقلات»). ریل تخفیف روی بلوک نارنجی توپر می‌نشیند.
- **بخش‌های امضا:** نوار جستجوی هیرو با انتخابگر آدرس، سه عدد آماری، نوار
  چهارتایی «تعهد تحویل»، دو بنر گرادیانی.
- **فوتر:** کامل — لوگو، دکمه‌های اپ، نوار خدمات، پنج ستون لینک، نماد اعتماد و
  متن سئو.
- **منطق:** گرم و پرتراکم، شبیه اپ سفارش غذا و سوپرمارکت. کرم و نارنجی حس
  تازگی و سرعت می‌دهد؛ گردی زیاد (`--sp-radius: 12px`) لحن را دوستانه می‌کند.

---

## ۲ — آکوا (Aqua) · سرد · `home-2-aqua.html`

- **پالت:** اصلی `#0e7490` (فیروزه‌ای) · تاکید `#f59e0b` (کهربایی) ·
  پس‌زمینه `#f1f5f9`
- **معماری:** هیروی دوستونه‌ی متقارن. تصویر در یک ستون و **کارت انتخاب زمان
  تحویل** که لبه‌ی پایین تصویر را می‌پوشاند — همان الگوی «کارت اقدام روی هیرو».
- **دسته‌بندی:** شبکه‌ی ۵ ستونی از کارت‌های مربعی با حاشیه — مرتب‌تر و
  اداری‌تر از ریل گرد دموی اول.
- **کالای منتخب:** چیدمان بنتو — یک بلوک بزرگ ۲×۲ برای پیشنهاد ویژه و هشت کارت
  کالا در اطرافش.
- **بخش‌های امضا:** کارت زمان تحویل، بنر سه‌تایی دسته‌بندی، نوار اعتماد.
- **فوتر:** فشرده‌تر، با فرم خبرنامه به‌جای نماد اعتماد.
- **منطق:** سرد، تمیز و «قابل اعتماد». گردی کمتر (`--sp-radius: 8px`)، سایه‌های
  ملایم‌تر و پس‌زمینه‌ی خاکستری-آبی. برخلاف دموی اول که گرم و شلوغ است، اینجا
  فضای خالی بیشتر و کنتراست کمتری هست.

---

## ۳ — گرافیت (Graphite) · خنثی/تیره · `home-3-graphite.html`

- **پالت:** اصلی `#a3e635` (لیمویی) · تاکید `#fb923c` · پس‌زمینه `#0f1115`
- **معماری:** بنر تیره‌ی تمام‌عرض با تیتر بسیار درشت
  (`clamp(2rem, 6vw, 4rem)`) و کمترین عناصر ممکن. بدون تصویر در هیرو —
  فقط تایپ و یک نوار مزیت.
- **دسته‌بندی:** کاشی‌های تک‌رنگ (`grayscale`) که با هاور رنگی می‌شوند و کمی
  بزرگ‌نمایی می‌گیرند.
- **کالای منتخب:** بلوک «پیشنهاد امروز» (متن + عکس + ستون چهارتایی تخفیف‌ها) و
  سپس یک شبکه‌ی متراکم ۲۰تایی که قیمت را برجسته می‌کند.
- **فوتر:** باریک — یک ردیف لوگو، لینک‌های حقوقی و شبکه‌های اجتماعی.
- **منطق:** «سوپرمارکت شبانه». تیره، خنثی و قیمت‌محور. لیمویی تنها رنگ سیگنال
  است و فقط روی اقدام‌ها می‌نشیند. برخلاف دو دموی دیگر، اینجا تصویر نقش
  تزئینی ندارد و همه‌چیز به عدد ختم می‌شود.

---

## جدول جمع‌بندی

| # | نام | حالت | اصلی | تاکید | هیرو | دسته‌بندی | فوتر |
|---|-----|------|------|-------|------|-----------|------|
| ۱ | تازه | گرم | `#f2600c` | `#16a34a` | کلاژ + جستجو | قرص گرد | کامل |
| ۲ | آکوا | سرد | `#0e7490` | `#f59e0b` | دوستونه + کارت | کارت مربعی | فشرده + خبرنامه |
| ۳ | گرافیت | خنثی | `#a3e635` | `#fb923c` | بنر تیره | کاشی تک‌رنگ | باریک |

---

## قواعد افزودن

### افزودن صفحه‌ی جدید

1. تابع بدنه را در یکی از `tools/pages_*.py` بنویسید (فقط بدنه‌ی `<main>`).
2. یک ورودی در `build_manifest()` داخل `tools/build_pages.py` اضافه کنید:
   `file`، `group`، `label`، `blurb`، `title`، `description`، `body` و در صورت
   نیاز `css` / `js`.
3. `python tools/build_pages.py` سپس `python tools/shots.py --only <نام>` و
   `python tools/build_demo.py`.

کارت صفحه‌ی جدید خودکار در `demo.html` ظاهر می‌شود؛ هیچ فایل مشترکی دست
نمی‌خورد.

### افزودن پالت جدید

1. یک بلوک `.sp-theme--<نام>` در `superium-palettes.css` با همان مجموعه توکن.
2. کلاس بدنه‌ی صفحه را عوض کنید.
3. اگر چیدمان اختصاصی لازم دارید، در `superium-home.css` زیر
   `body.sp-theme--<نام>` بنویسید تا با بقیه تداخل نکند.

### قواعد کامپوننت

1. هیچ رنگی در کامپوننت hard-code نشود — فقط `var(--sp-*)`.
2. هیچ `left`/`right` فیزیکی نوشته نشود.
3. ستون‌های گریدی که تصویر می‌گیرند با `minmax(0, …)` تعریف شوند.
4. تصاویر همیشه `width` و `height` داشته باشند تا پرش چیدمان (CLS) رخ ندهد.
5. کنترل‌های آیکونی حتماً `aria-label` داشته باشند.