سیستم طراحی

زبان طراحیای که ranui از آن ساخته شده، و فهرست کامل توکن‌هایی که آن را بیان می‌کنند: هر ویژگی سفارشی سراسری --ran-* که کتابخانه اعلام می‌کند، با مقدارش در هر دو پوسته. کامپوننت‌ها به‌جای نوشتن مقدار ثابت این توکن‌ها را می‌خوانند، پس بازنویسی یک توکن، ظاهر هر چیزی را که آن را مصرف می‌کند عوض می‌کند.

سه صفحه به سه پرسش متفاوت پاسخ می‌دهند و عمداً از هم جدا مانده‌اند:

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

زبان: Geist

توکن‌های ranui بر پایه Geist است، سیستم طراحی متن‌باز Vercel. هر مقیاس رنگ یک نردبان از وظیفه‌های ثابت است، برای هر پله یکی، نه مجموعه‌ای از سایه‌ها که از میانشان انتخاب کنید: پله ۲۰۰ «خاکستریِ کمی تیره‌تر» نیست، «پس‌زمینه هاور» است. وقتی وظیفه یک پله تثبیت شد، انتخاب رنگ برای یک حالت تعاملی به‌جای داوری، به یک جست‌وجو تبدیل می‌شود.

ranui همان نردبان را به‌شکل مقیاس‌های --ran-* خود برمی‌دارد، توکن‌های معنایی را رویش می‌گذارد، و Geist Sans / Geist Mono را به‌عنوان قلم‌های پیش‌فرض همراه می‌آورد.

دو لایه

لایه ۱: پالت پایه. همان مقیاس‌های خام پایین. به‌ندرت مستقیم مصرف می‌شوند.

لایه ۲: توکن‌های معنایی. --ran-color-* و هم‌خانواده‌هایش، که روی لایه ۱ نگاشت شده‌اند. همین لایه را مصرف کنید. حالت تیره تنها لایه ۱ را از نو تعریف می‌کند، پس هر توکن معنایی از راه var() می‌چرخد و هیچ‌جای کتابخانه بازنویسیِ تیرهٔ کامپوننت‌به‌کامپوننت وجود ندارد.

--ran-gray-1000        →  #171717 (روشن) / #ededed (تیره)        ← لایه ۱، می‌چرخد
--ran-color-text       →  var(--ran-gray-1000)                    ← لایه ۲، دنبال می‌کند
--ran-btn-color        →  var(--ran-color-text, …)                ← توکن کامپوننت

همین زنجیره تمام معماری است: یک پله پایه را عوض کنید و همه‌جا منتشر می‌شود؛ یک توکن معنایی را عوض کنید و یک نقش عوض می‌شود؛ یک توکن کامپوننت را عوض کنید و یک عنصر عوض می‌شود.

رنگ

نردبان

هر مقیاس رنگ از 100 تا 1000 می‌رود و هر پله یک وظیفه ثابت دارد:

پس‌زمینه‌ها

خاکستری — --ran-gray-100..1000

مقیاسی که پشت متن و کادرها و سطح‌ها ایستاده است.

خاکستری آلفا — --ran-gray-alpha-100..1000

نیمه‌شفاف است، پس روی هر سطحی می‌نشیند: انتخاب درست برای یک پرده، یک شست‌وشوی هاور، یا جداکننده‌ای که باید روی محتوای ناشناخته بنشیند.

آبی — --ran-blue-100..1000

برای پیوندها و حلقه فوکوس کنار گذاشته شده است.

قرمز — --ran-red-100..1000

خطر و ارور.

کهربایی — --ran-amber-100..1000

هشدارها.

سبز — --ran-green-100..1000

موفقیت.

توکن‌های معنایی رنگ

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

--ran-color-primary-hover / -active دو مقدار ثابت لایه معنایی‌اند: به‌جای حرکت در طول یک مقیاس، به‌سوی پس‌زمینه صفحه گام برمی‌دارند، پس حالت تیره مستقیم از نو تعریفشان می‌کند.

هر رنگ تأکیدی چه معنایی دارد

• primary تک‌رنگ است: در روشن سیاه روی سفید، در تیره سفید روی سیاه (لحن برند Geist، <r-button type="primary">). متن و آیکن‌های رویش --ran-color-primary-text را به کار می‌برند که همراهش می‌چرخد. توکن جداگانه‌ای برای «کنتراست» نیست: primary خودش پرکنتراست‌ترین کنش است.
• آبی کنار گذاشته شده برای پیوندها (--ran-color-link) و حلقه فوکوس. جایگزینی برای primary نیست.
• سبز = موفقیت · کهربایی = هشدار · قرمز = خطر. هرکدام یک معنا.

چیزی به نام --ran-color-error وجود ندارد؛ توکن --ran-color-danger است. var()ی که ویژگی اعلام‌نشده‌ای را نام ببرد به هیچ حل نمی‌شود و کل اعلان بی‌صدا دور ریخته می‌شود؛ به همین دلیل ارزش دارد نام مشکوک را به‌جای حدس زدن با همین جدول بسنجید.

فاصله

شکاف میان چیزها: padding، margin، gap. واحد پایه ۴ پیکسل با نه مقدار، نه بیشتر:

عدد، ضریب ۴ پیکسل است، پس مقیاس می‌پرد: --ran-space-5 وجود ندارد. نکته همین است: مجموعه‌ای محدود همان چیزی است که ریتم یک صفحه را می‌سازد.

اندازه

ابعاد خودِ عنصر: اندازه آیکن، ارتفاع کنترل، کنترل‌های کوچک مربعی یا مستطیلی.

این عمداً مقیاسی جدا از فاصله است و قاطی کردنشان خطایی است که ماشین می‌گیرد (sizing-scale). این دو دامنه و پیشرَوی متفاوتی دارند (مقیاس فاصله‌ای که از ۴ پیکسل دوبرابر می‌شود، برای اندازه آیکن و کنترل مقدارهای ناجوری می‌دهد) و مصرف‌کننده باید بتواند یکی را کوک کند بی‌آنکه دیگری را به هم بزند: بزرگ‌تر شدن یک آیکن نباید هر شکافی را هم که اتفاقاً همان مقدار پیکسلی را دارد پهن کند. اگر پله‌ای عددی با پله‌ای از فاصله یکی درآید (--ran-size-4 و --ran-space-6 هر دو ۲۴ پیکسل‌اند) این تصادف است، نه هم‌نامی.

بُعدی که واقعاً یک‌باره است و هیچ کامپوننت دیگری در آن شریک نیست (مثلاً min-width یک منو) به‌جای اینکه به زور در یک پله جا داده شود، همان توکن سادهٔ کامپوننت با مقدار جایگزین ثابت خودش می‌ماند.

تایپوگرافی

متن بر پایه نقش سامان می‌یابد و نقش، قلم و اندازه و وزن و ارتفاع خط را با هم تعیین می‌کند:

دو توکن فقط برای اینکه یک نقش درست بنشیند وجود دارند:

Geist سقف وزن را روی ۶۰۰ (سمی‌بولد) می‌گذارد. تأکید از اندازه و فاصله می‌آید نه از قلمی سنگین‌تر. --ran-text-copy-3 وجود ندارد: پله ۱۲ پیکسل همان --ran-text-label-3 است.

قلم‌ها

ranui هر دو قلم را خودش میزبانی می‌کند (وزن متغیر ۱۰۰ تا ۹۰۰، SIL OFL 1.1)، پس یک import آن‌ها را بدون وابستگی به CDN بار می‌کند:

import 'ranui/fonts'; // برای باندلرها

<link rel="stylesheet" href="…/ranui/dist/fonts/fonts.css" />

بدون آن، توکن‌ها به پشته‌های قلم سیستم برمی‌گردند؛ همه‌چیز باز هم کار می‌کند، فقط بدون قلم‌های Geist.

شعاع گوشه

ارتفاع سایه

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

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

چیدمان لایه‌ها

لایه‌های شناور به <body> پرتال می‌شوند، پس به رده‌ای صریح نیاز دارند:

نردبان از ۱۰۰۰ آغاز می‌شود تا از قاب معمول صفحه بگذرد (نوارهای ناوبری و پرده‌ها معمولاً در دهگان‌اند). یک رده را روی :root بازنویسی کنید، یا به تفکیک کامپوننت (--ran-dropdown-host-z-index، --ran-modal-root-z-index، --ran-message-z-index)، اما هرگز با !important.

حرکت

خانواده spring از فنرهای کوک‌شده SwiftUI تقطیر شده است (response/damping به یک بزیهٔ تک‌گذر از هدف فرو کاسته شده).

این‌ها را تنها با ویژگی‌های حرکتی جفت کنید: transform، opacity، هندسه جعبه. ویژگی‌های پالت (background-color، color، border-color، box-shadow، fill، stroke) عمداً هیچ گذار پیش‌فرضی ندارند، چون CSS نمی‌تواند تعامل را از چرخش پوسته تشخیص دهد: هر محوی که به یک رنگ بیفزایید، هنگام تعویض روشن↔تیره هم شلیک می‌شود. با این حال هر کامپوننت یک قلاب --ran-*-transition دارد، اگر خواستید دوباره روشنش کنید.

فوکوس

حلقه دو لایه است: یک حلقه درونی به رنگ پس‌زمینه و یک حلقه بیرونی آبی؛ پس روی هر سطحی دیده می‌شود و به‌جای دنبال‌کردنِ primaryِ حالا تک‌رنگ، آبی می‌ماند.

--ran-focus-ring-inverse-color عمداً در حالت تیره از نو تعریف نمی‌شود: برای کامپوننتی هست که سطح خودش صرف‌نظر از پوسته صفحه همیشه تیره است (نوار کنترل r-player روی هر ویدیویی) و آن سطح با تغییر صفحه عوض نمی‌شود.

ابتدایی‌های پوسته

همان چند مقدار ساختاری که کامپوننت‌ها مشترک دارند و رنگ و اندازه و متن نیستند. عمداً کمینه نگه داشته شده‌اند: این لایه زمانی خیلی بزرگ‌تر بود و بیشترش همراه بسته‌های پوسته برداشته شد.

حالت تیره چه چیزی را از نو تعریف می‌کند

data-ran-theme="dark" روی <html> (یا روی هر زیردرختی، پوسته‌بندی را ببینید) فقط پالت پایه را از نو تعریف می‌کند، با سه استثنا که از راه یک مقیاس حل نمی‌شوند:

• تمام لایه ۱: هر پله خاکستری، خاکستری آلفا، آبی، قرمز، کهربایی و سبز، و هر دو پس‌زمینه؛
• --ran-color-bg-elevated که در تیره به --ran-gray-100 اشاره می‌کند تا کارت از صفحه سیاه بالا بیاید نه اینکه در آن گم شود؛
• --ran-color-primary-hover / -active که مقدار ثابت‌اند نه ارجاع به مقیاس؛
• هر سه رده سایه، که برای زمینه تیره از نو کوک شده‌اند.

باقی همه‌چیز (هر توکن معنایی دیگر، هر اندازه، هر مدت) یک بار تعریف می‌شود.

توکن‌های کامپوننت

پایین‌تر از لایه معنایی، هر کامپوننت قلاب‌های خودش را با این نام‌گذاری در اختیار می‌گذارد:

--ran-{component}-{element}[-{state}]-{property}

مثلاً --ran-btn-hover-background، --ran-select-search-active-border-width. این‌ها به‌طور پیش‌فرض به توکن‌های معنایی برمی‌گردند: var(--ran-btn-background, var(--ran-color-primary, #171717))؛ پس بازنویسی یک توکن معنایی به همه‌شان می‌رسد و بازنویسی یک توکن کامپوننت، تغییر را به یک عنصر محدود می‌کند.

فهرست کاملِ تولیدشده در style-tokens-public.md در مخزن است؛ API به‌تفکیک عنصر اینجاست. برای شیوه اعمالشان پوسته‌بندی را ببینید.

به‌کارگیری توکن‌ها در CSS خودتان

.panel {
  background: var(--ran-color-bg-elevated);
  color: var(--ran-color-text);
  border: var(--ran-skin-border-width) var(--ran-skin-border-style) var(--ran-color-border);
  border-radius: var(--ran-radius-md);
  padding: var(--ran-space-4);
  box-shadow: var(--ran-shadow-elevated);
}

سه قاعده آن را در حالت تیره امن نگه می‌دارد:

1. برای هرچه باید از پوسته پیروی کند هیچ کد شانزده‌شانزدهی خامی ننویسید.
2. مقدار جایگزین باید توکنی را نام ببرد که می‌چرخد: var(--ran-color-text, var(--ran-gray-1000))، نه var(--ran-color-text, #171717).
3. مقدار جایگزین باید توکنی موجود را نام ببرد، وگرنه اعلان دور ریخته می‌شود و عنصر بی‌صدا همان چیزی را که به ارث برده نگه می‌دارد.

هر توکن سراسری‌ای که کتابخانه اعلام می‌کند در همین صفحه فهرست شده، و اگر توکنی بدون مستندسازی در اینجا افزوده شود یک تست واحد شکست می‌خورد. توکن‌های محدود به کامپوننت جداگانه تولید می‌شوند، در style-tokens-public.md.