دامنهٔ سیستم طراحی

معرفی

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

سه لایه

کدام سطح، کدام لایه

اولین ردیفی که درست است، جواب است:

• ردیف اول دربارهٔ سکوست، نه نوع سطح: برنامهٔ داده‌ای روی React 18 یا Tailwind v3 تا ارتقا به React 19 و Tailwind v4 فقط لایهٔ 1 را می‌گیرد و بعد هر سه را. اپی روی آن سکو که از قبل کامپوننت‌های پرتو 3.x را به کار می‌برد، تا ارتقا روی 3.x می‌ماند؛ نسخهٔ 4.0 اولین نسخه‌ای است که آن سکو را پشتیبانی نمی‌کند. صفحه‌ای که React نیست، برای گرفتن سیستم طراحی به React بازنویسی نمی‌شود.
• مسیر بیرون از قاب (مسیرهای بیرون از قاب) کامپوننت‌هایی را که لازم دارد می‌گیرد — منبع PDF نمودارها، جدول‌ها و BulletinViewer خود را، با پالت روشن (data-theme="light" روی <html>) — اما هیچ‌وقت قاب یا قالب صفحه را.
• نسخهٔ منشعب فقط لایهٔ 1 را می‌گیرد تا همگام‌سازی با نسخهٔ اصلی ارزان بماند؛ سایت بازاریابی فقط کامپوننت‌هایی را که لازم دارد.
• lint: برنامهٔ داده‌ای parto.configs.recommended را فعال می‌کند و سطحی با لایه‌های 1 و 2 parto.configs.components را، همان قاعده‌ها بدون سه قاعدهٔ صفحه.

نیازمندی‌ها

• React 19 (react و react-dom نسخهٔ 19؛ peer dependency >=19). پکیج فقط روی React 19 ساخته و آزموده می‌شود. کامپوننت‌هایی که تابع ساده‌اند (DropdownMenu*، Sheet*، ContextMenu*، Table*، Avatar، Label، Toggle و دیگران) روی React 18 ref داده‌شده به خود را دور می‌اندازند (React هشدار «Function components cannot be given refs» می‌دهد)، و GatedActionی که پنجره‌ای را باز می‌کند ref آن را گم می‌کند: پس از بسته شدن پنجره فوکوس به آن برنمی‌گردد.
• Tailwind v4 برای لایه‌های 2 و 3، با دو خط در CSS. Tailwind v3 پشتیبانی نمی‌شود: کلاس‌های کامپوننت‌ها نحو نسخهٔ 4 دارند و stylesheet ازپیش‌ساختهٔ پرتو (styles.css) یک build کامل Tailwind v4 است؛ یا build نسخهٔ 3 را متوقف می‌کند یا، کنار آن روی صفحه، کلاس‌های خود اپ را عوض می‌کند (Tailwind v3 و React 18).
• Next.js 15 یا بالاتر (React 19) یا هر باندلر Vite/webpack؛ در Next.js پکیج در transpilePackages.

لایهٔ 1 بدون React و Tailwind

سطحی که React 19 و Tailwind v4 ندارد، لایهٔ 1 را از tokens.css می‌گیرد: یک stylesheet ساده با توکن‌های هر دو تم (var(--brand-default)، var(--foreground-default)، var(--border-default)، var(--layout-page-inset)، …)، فونت یکان بخ و قاعدهٔ رقم‌ها. reset، کلاس utility، @property و @layer ندارد و همهٔ قاعده‌هایش specificity صفر دارند (:where). این سطح پکیج 4.x را نصب نمی‌کند: React 18 نمی‌تواند (npm با ERESOLVE متوقف می‌شود؛ هرگز --legacy-peer-deps، --force یا override)، و اپی که روی 3.x است در node_modules نسخهٔ 3.x دارد که tokens.css ندارد. فایل‌های یک نسخهٔ دقیق را با npm pack @partodata/ui@4.0.0 برمی‌دارد و tokens.css را همراه پوشهٔ assets (فونت) کنار آن کپی و با <link> بار می‌کند؛ صفحه‌ای که پوشهٔ فایل ثابت ندارد، همان نسخه را از CDN پیوند می‌دهد (دستور کامل).

• رقم‌ها از lang پیروی می‌کنند: در متن یکان بخ زیر lang="fa" رقم لاتین فارسی کشیده می‌شود؛ عنصری با lang دیگر (شناسه‌ای مثل نام کاربری یا IP با lang="en"، صفحهٔ عربی) رقم خودش را نگه می‌دارد، و فونت دیگری روی صفحه دست نمی‌خورد.
• نشانگر تم روی <html> (data-theme="light" یا "dark") تم توکن‌ها و color-scheme را تعیین می‌کند؛ کلاس dark یا light فقط مقدار توکن‌ها را عوض می‌کند. بدون نشانگر، توکن‌ها مقدار تیره دارند.
• متغیری که سایت با نام یکی از توکن‌ها تعریف کرده، اگر بیرون از @layer باشد مقدار سایت می‌ماند؛ داخل @layer (مثل @theme در Tailwind v4) مقدار tokens.css غلبه می‌کند و متغیر سایت باید تغییر نام دهد. جز این و رقم‌ها و color-scheme، تا CSS سایت توکنی را نخواند چیزی در صفحه عوض نمی‌شود.
• لایهٔ 1 مقیاس تایپ ندارد: سایت اندازه‌ها را از مقدار نقش‌ها (4.0) می‌گذارد، ارتفاع خط در پرانتز — micro 10px، mini 11px، caption 12px (18px)، label 14px (22px)، body 14px (22px)، subheading 14px (22px، وزن 600)، heading 18px (28px، 600)، display 22px (32px، 600).
• ایمیل tokens.css را بار نمی‌کند (کلاینت‌های ایمیل <link>، var() و color-mix() را حذف می‌کنند): رنگ‌های تم روشن را hex و درون‌خطی از palette-light.json همان نسخه می‌نویسد، کنار tokens.css در dist.
• تقویم جلالی با همان کتابخانه‌ای است که پرتو به کار می‌برد، date-fns-jalali.

مرز لایهٔ برنامه

• هر صفحهٔ برنامهٔ داده‌ای یکی از قالب‌های صفحه است، داخل یک ProductFrame؛ گزینه‌های قاب (بدون منو، بدون نوار برای نمایشگر بی‌کاربر، زبان، خط پایانی، سربرگ چاپ) و قالب‌ها نیازهای حرفه‌ای این برنامه‌ها را پوشش می‌دهند.
• سایت بازاریابی یا صفحهٔ فرود قاب و قالب صفحه نمی‌گیرد: ساختار آن سایت کار خودش است و فقط لایه‌های 1 و 2 را به کار می‌برد.
• وقتی صفحه‌ای از برنامهٔ داده‌ای در هیچ قالبی جا نمی‌شود، CustomPage با برچسب DS-GAP است و نیاز به مسئول طراحی گزارش می‌شود؛ نیازی که دو بار تکرار شود، الگو می‌شود.

بهترین روش‌ها و دام‌های رایج

صفحات مرتبط

• نصب و راه‌اندازی — تنها مسیر لایه‌های 2 و 3، و tokens.css لایهٔ 1 برای سکوهای دیگر.
• قاب محصول — لایهٔ سوم: قاب یک بار، و مسیرهایی که بیرون از آن‌اند.
• انتخاب قالب صفحه — لایهٔ سوم: هر صفحهٔ برنامهٔ داده‌ای یک قالب است.
• تمپلیت شروع — یک برنامهٔ داده‌ای کامل روی هر سه لایه.