مشارکت و نگهداری

ساختار مخزن

• فهرستtokens/ منبع همهٔ مقدارها؛ فقط این‌جا ویرایش کنید

  • فهرستprimitive/ مقدارهای خام: پالت، قلم، فاصله

    • …
  • فهرستsemantic/ نقش‌ها، با مقدار حالت تیره

    • …
• فهرستicons/carbon/ همهٔ آیکن‌های IBM Carbon؛ ساخته‌شده با npm run icons:import

  • …
• فهرستlib/

  • components.css استایل کامپوننت‌ها، فقط با متغیرهای –hq-
• فهرستsrc/

  • فهرستcontent/docs/ صفحه‌های سایت؛ هر پوشه یک بخش منو

    • …
  • فهرستcomponents/docs/ ابزارهای نمایش توکن و نمونه در صفحه‌ها

    • …
  • فهرستgenerated/ ساخته‌شده از tokens/؛ ویرایش نکنید

    • …
• فهرستpublic/

  • فهرستdist/ فایل‌های قابل دانلود؛ ساخته‌شده از tokens/ و lib/

    • …
• فهرستtemplates/ قالب صفحهٔ کامپوننت

  • …
• scripts/build-tokens.mjs ساخت خروجی‌ها از توکن‌ها

اصلاح یک مقدار

1. مقدار را فقط در tokens/ تغییر دهید. برای نقش‌ها، مقدار حالت تیره در $extensions["hq.modes"].dark همان توکن است.
2. npm run dev را اجرا کنید و صفحه‌های رنگ، نویسه‌نگاری و کامپوننت‌ها را ببینید؛ همه از همین منبع خوانده می‌شوند.
3. تغییر را در تازه‌ها ثبت کنید.
4. یک Pull Request باز کنید. پس از ادغام در شاخهٔ main، سایت خودکار منتشر می‌شود.

افزودن یک کامپوننت

1. templates/component.mdx را در src/content/docs/components/ کپی کنید و نامش را عوض کنید (مثلاً button.mdx).
2. استایل کامپوننت را در lib/components.css با پیشوند hq- و فقط با متغیرهای --hq- بنویسید. هیچ رنگ یا اندازهٔ خامی در CSS ننویسید.
3. اگر مقداری لازم دارید که توکن ندارد، اول آن را در tokens/ اضافه کنید.
4. نمونه‌ها را با <Example html={…} /> بسازید تا نمونهٔ زنده و کد همیشه یکی باشند.
5. وضعیت را در frontmatter با status: draft شروع کنید و پس از تایید به review و stable ببرید.

افزودن یک صفحه یا بخش

هر فایل .mdx در یکی از پوشه‌های src/content/docs/ خودکار در منوی همان بخش می‌آید. ترتیب را با sidebar.order در frontmatter تعیین کنید. برای یک بخش تازه در منو، پوشه را بسازید و یک خط در astro.config.mjs اضافه کنید.

به‌روزرسانی آیکن‌ها

آیکن‌ها از نسخهٔ مشخصی از بستهٔ @carbon/icons وارد شده‌اند. برای نسخهٔ تازه:

npm install --save-dev --save-exact @carbon/icons@<نسخه>
npm run icons:import

سپس تغییرهای پوشهٔ icons/carbon/ را commit کنید.

قواعد نگارش

همهٔ متن‌های این سایت تابع قواعد نگارش هارمونیک‌اند: «مساله» نه «مسئله»، «هٔ» برای کسرهٔ اضافه، نشانه‌ها و رقم‌های فارسی.