گرامر بصری

// eslint-disable-next-line parto/no-hollow-surface -- Grammar deviation: G2 — <reason>

اصل

سطح و ساختار از ترکیب می‌آید، نه از رنگ. هر بلوک محصور یک ظرف است: پرکننده + مرز + شعاع + سایهٔ کوچک، هر چهار با هم. بقیهٔ آرامش صفحه از کم‌کردن می‌آید: لایهٔ کمتر پیش از داده، تکرار کمتر، رنگ کمتر، کنترل کمتر.

این صفحه راهنمای هر کسی (و هر ایجنتی) است که صفحه می‌سازد یا محصولی را اصلاح و مهاجرت می‌کند. قاعده‌ها شمارهٔ G1…G20 دارند؛ در توضیح MR فقط شمارهٔ قاعده‌ای را بنویسید که اجرا کردید یا آگاهانه از آن منحرف شدید (بالا: پروتکل انحراف). همین متن در AGENTS.md بستهٔ @partodata/ui (بخش 10) و در مهارت‌های parto-ui-build-page، parto-ui-migrate-page و parto-ui-check هم هست: npx --no parto-ui guide surfaces --full.

نمونه بصری

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

توکن‌ها عوض نمی‌شوند

در تم تیره پلهٔ بوم ← ظرف (فقط رنگ) در پرتو با Studio یکی است و در تم روشن از Studio قوی‌تر؛ مرزها یکی‌اند. پس «بلوکی هم‌رنگ بوم» هرگز از توکن نمی‌آید: از جایی می‌آید که ظرف اصلاً به کار نرفته. روشن‌تر کردن surface-100 فقط همهٔ ظرف‌های درست را هم عوض می‌کند. پرکننده به‌تنهایی هم جدایی نمی‌سازد (حدود 1.05)؛ مرز چهار تا ده برابر قوی‌تر است، پس جفت «پرکننده + مرز» لازم است.

• کف مجاز برای هر ظرف روی لایهٔ بالاترش: کنتراست پرکننده ≥ 1.04 و مرز ≥ 1.15، در هر دو تم.
• روش اندازه‌گیری مرز: کف ≥ 1.15 روی رنگ مرز ترکیب‌شده با بوم است (آنچه آزمون سطوح حساب می‌کند). روی صفحه مرز روی پرکنندهٔ خودِ ظرف می‌نشیند و پیکسل روشن‌تر است: لبهٔ واقعی جدول در تم روشن بوم 245، مرز 234، داخل 255، یعنی 1.10 (Supabase Studio 1.09) و در تیره 1.28. نشاندن مرز روی بوم (background-clip: padding-box) روی جدول واقعی عکس شد: پیکسل مرز 205 (نسبت 1.46) چون سایهٔ کارت از زیر کادر مرزِ ترسیم‌نشده پیدا می‌شود؛ خط سنگین‌تر از Studio است و پذیرفته نشد. قاعدهٔ لبهٔ عکس‌برداری‌شده: ≥ 1.08 روشن (برابر Studio) و ≥ 1.15 تیره؛ توکن و آزمون سطوح عوض نمی‌شوند.
• دو ظرف هم‌سطح کنار هم (جدول و نمودارش) یک پرکننده دارند؛ یکی توخالی و دیگری پر ممنوع.
• یک پلهٔ «روشن‌تر» (surface-300) به‌عنوان ذخیره هست و فقط با عکس قبل/بعد روی صفحهٔ واقعی تصمیم‌گیری می‌شود، نه با عدد. تراکم ردیف جدول (40/44) هم تا آزمون واقعی دست نمی‌خورد.

جدول تصمیم: چه چیزی روی کدام لایه

تنها استثنا: Data Grid تمام‌عرض (جدول لبه‌به‌لبه در CustomPage layout="fill") که قابش را نوار ابزار و فوترِ خودش می‌سازد. جدول‌های معمول صفحه همیشه ظرف دارند.

مرز، شعاع، سایه، فاصله

ممنوع: مرز دور متنِ تنها، دو مرز تودرتو، border-2 روی بلوک، مرز بدون پرکننده روی بلوک داده، پرکننده بدون مرز روی ظرف.

کالبد بخش و صفحه

[عنوان بخش  heading 18/600]            [اکشن‌های بخش]        ← L0
[توضیح یک‌خطی، رنگ lighter]                                    ← L0
┌───────────────────────────────────────────┐
│ L1: محتوا (جدول / نمودار / فرم / نخ)      │  پرکننده + مرز + شعاع + سایه
└───────────────────────────────────────────┘
فاصلهٔ 48 تا بخش بعد

• همهٔ قالب‌ها: حداکثر دو لایه (تب، نوار منبع، نوار ابزار، نوار خلاصه، نوار هشدار) بین عنوان صفحه و اولین ردیف داده.
• ListPage: عنوان و یک اکشن اصلی ← یک ردیف ابزار (جست‌وجو، حداکثر 3 فیلتر پرتکرار، «فیلتر بیشتر»؛ حداکثر 8 کنترل) ← DataTable. فیلتر زیاد: ستون فیلتر قاب. شمارندهٔ وضعیت‌ها جزو تب‌هاست، نه کارت پرکننده. پست‌ها: فید کارت.
• DashboardPage: عنوان و بازهٔ تاریخ ← یک ردیف 3 تا 4 شاخص عمل‌پذیر یا مقایسه‌دار ← DashboardSectionها با DashboardChart ← جدول «نیازمند اقدام». عرض wide.
• DetailPage: سربرگ هویت ← تب (بیش از 3 بخش) ← DetailSectionها: عنوان روی بوم، محتوا در L1. ستون کناری هم L1.
• SettingsPage / FormPage: عرض narrow؛ هر گروه یک SettingsSection با ذخیرهٔ خودش؛ FormPage یک L1 و یک ذخیره.
• صفحهٔ جست‌وجو (ListPage query): ردیف جست‌وجو و فیلترهای پرتکرار در یک ردیف؛ شمار نتایج در سربرگ نتایج؛ فقط یک منبع.

قوانین اجباری

ده جفت، هر کدام دو رندر واقعی روی بوم صفحه؛ نیمهٔ «نادرست» اشتباه را عمداً مرتکب می‌شود. اگر پنل در تم تیره همرنگ بوم دیده شد، تم را عوض کنید و دوباره نگاه کنید.

G1 و G2: جدول روی ظرف می‌نشیند

Table خام ظرف ندارد: ردیف‌هایش در تم تیره دقیقاً رنگ بوم‌اند و در تم روشن فقط یک نوار بی‌حاشیه می‌بینید.

G4: قاب در قاب ممنوع

داخل یک ظرف فقط L2 (بدون مرز) یا یک خط مجاز است. DataTable هرگز داخل Card نمی‌رود و Table خام همیشه می‌رود.

G2 و G3: بلوک توخالی نه

bg-background، bg-transparent، bg-sidebar و bg-alternative رنگ خود بوم‌اند؛ پوستهٔ بلوک نیستند.

G1: فرم تعاملی روی ظرف

هر گروه فرم یک ظرف با دکمهٔ «ذخیره»ٔ خودش است (SettingsSection، FormPage).

G14: شبکهٔ شاخص بدون یتیم

5 تا 6 کارت در ردیف‌های سه‌تایی، 7 تا 8 در چهارتایی؛ ردیف آخر هرگز یک کارت تنها یا نیمه‌خالی نیست. شبکهٔ شاخص قالب‌ها (kpis، summary) این را خودکار از شمار کارت‌ها می‌سازد.

G15: ستون فیلتر، دو گروه پرتکرار باز

گروه‌های پرتکرار باز، بقیه بسته با خلاصهٔ فعالِ آشکار («2 فعال»)؛ ستون دوم فقط یک نقش دارد: فیلتر.

G11 و G12: لایه‌های پیش از داده

حداکثر دو لایه (تب، نوار منبع، نوار ابزار، خلاصه، هشدار) بین عنوان صفحه و اولین ردیف داده؛ یک ردیف ابزار با حداکثر 8 کنترل.

G13: یک اطلاعات، یک شکل

شمار هر وضعیت یا در تب است یا در کارت یا در فیلتر، نه چند جا.

G10: رنگ فقط برای وضعیت

یک رنگ برند؛ رنگ معنایی فقط برای وضعیت و حداکثر 4 رنگ معنایی در یک صفحه‌نمایش؛ ابر کلمات تک‌رنگ با شدت.

G19: مهاجرت یعنی بازطراحی

پیش از لمس هر صفحه سه پرسش را در MR جواب بدهید (کار صفحه و کاربرش، بخش تکراری، نزدیک‌ترین نمای Studio) و DS را پیش از قضاوت بصری به آخرین major ببرید. جایگزینی قالب با همان بخش‌ها و همان ترتیب ناقص است.

موارد استفاده رایج

جدول کوچک در یک بخش

import { Card, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@partodata/ui'

export function Accounts() {
  return (
    <Card>
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>اکانت</TableHead>
            <TableHead>منشن</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          <TableRow>
            <TableCell>فروشگاه آفتاب</TableCell>
            <TableCell>1,240</TableCell>
          </TableRow>
        </TableBody>
      </Table>
    </Card>
  )
}

بخش جزئیات با محتوای آزاد

DetailSection محتوایی را که خودش سطح ندارد (نخ نظر، timeline، key-value، Table خام، پست با layout="row") خودکار در یک ظرف L1 می‌گذارد؛ محتوایی که خودش سطح است (DataTable، ChartCard، Card، پست کارتی) را دوبار قاب نمی‌گیرد. برای محتوای سفارشی که سطح خودش را می‌کشد surface="none" بدهید.

چه چیزی خودکار بررسی می‌شود

• lint: parto/surface-for-blocks (جدول یا نمودار مستقیم در PageSection و مانند آن)، parto/no-hollow-surface (بلوک مرزدار و دارای padding روی رنگ بوم)، parto/no-card-in-card (ظرف در ظرف، DataTable در Card). هر سه در 7.2 در سطح warn هستند و پس از baseline محصولات error می‌شوند.
• کنسول توسعه: Table خام یا نمودار روی بوم، و ظرف در ظرف، یک‌بار هشدار می‌دهند. هر ظرف نشانهٔ data-surface دارد؛ Dialog، Sheet و Popover نشانهٔ overlay دارند و تودرتویی را از نو شروع می‌کنند. کامپوننت سفارشی که سطح خودش را می‌کشد، روی ریشه‌اش data-surface="none" می‌گذارد.
• آزمون سطوح در مخزن DS: در هر دو تم، پرکنندهٔ هر ظرف ≥ 1.04 و مرز ≥ 1.15، صفر ظرف تودرتو، صفر بلوک بی‌ظرف.

چه نکنیم

این فهرست هم «پیش‌فرض قوی» است، نه قانون مطلق: انحراف با دلیل و یک خط در MR (بالا) مجاز است؛ بی‌صدا نه.

• توکن‌های سطح و مرز را برای «جداتر دیده شدن» روشن‌تر یا تیره‌تر نکنید؛ ظرف را به کار ببرید.
• پیش‌فرض DS (تراکم جدول، سایه، شعاع) را برای رسیدن به یک عدد عوض نکنید.
• برای نبودن کامپوننت مناسب، جایگزین زورکی نسازید: npx --no parto-ui gap add.
• کارت شاخص را برای پر کردن شبکه نسازید و بیش از 4 رنگ معنایی در یک صفحه نیاورید.
• متن راهنمای بلندتر از دو خط را داخل صفحه نگذارید: Popover یا Callout قابل‌جمع.
• هر کارت یک عنوان و حداکثر یک پیوند عمیق کوچک؛ نه چند دکمهٔ ghost.

قاعده‌های G1 تا G20 (فهرست فشرده)

همهٔ این بیست قاعده «پیش‌فرض قوی» هستند (دستهٔ دوم بالا)؛ دستهٔ سخت جدا و بدون انحراف است.

صفحات مرتبط

• رنگ‌ها: توکن‌های سطح (surface-100، canvas) و نقش هر کدام.
• عمق، گوشه و لایه‌بندی: سایه، شعاع و z-index.
• هندسهٔ صفحه: عرض قالب‌ها و ریتم فاصله.
• Table و DataTable: جدول خام در Card، DataTable با ظرف خودش.