{
  "title": "راهنمای مصرف توسعه‌دهنده — سیستم طراحی نانس",
  "slug": "team/frontend/design-system/developer-usage",
  "url": "/docs/team/frontend/design-system/developer-usage",
  "frontmatter": {
    "layout": "doc",
    "title": "راهنمای مصرف توسعه‌دهنده (Developer Usage)",
    "description": "نحوهٔ مصرف توکن‌های طراحی و بازتولید رابط کاربری مرجع در سیستم طراحی نانس",
    "version": "1.0.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-07-11",
    "updated_at": "2026-07-11",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "راهنمای مصرف توسعه‌دهنده — سیستم طراحی نانس",
      "content": "**Developer Usage Guide — Nons Design System**\n\nنحوهٔ مصرف توکن‌های طراحی (Design Tokens) و بازتولید رابط کاربری مرجع (به `preview/index.html` مراجعه کنید). این نقطهٔ ورود واحد برای توسعه‌دهندگانی است که سیستم را در یک محصول ادغام می‌کنند.\n\n> مستندات مرتبط: [تایپوگرافی](typography) · [حالت‌های تعاملی](interactive-states) · گزارش پوشش توکن‌ها (توسط نگه‌دارنده تکمیل می‌شود)\n\n---"
    },
    {
      "level": 2,
      "heading": "فهرست محتوا",
      "content": "1. [مدل ذهنی](#۱-مدل-ذهنی)\n2. [واژگان توکن‌های خروجی CLI](#۲-واژگان-توکن‌های-خروجی-cli)\n3. [حالت روشن / تاریک (Light / Dark)](#۳-حالت-روشن--تاریک-light--dark)\n4. [حالت‌های تعاملی](#۴-حالت‌های-تعاملی-مهم‌ترین-بخش)\n5. [بازتولید رابط کاربری مرجع](#۵-بازتولید-رابط-کاربری-مرجع)\n6. [انجام دهید / انجام ندهید](#۶-انجام-دهید--انجام-ندهید)\n7. [دریافت توکن‌ها](#۷-دریافت-توکن‌ها)\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. مدل ذهنی",
      "content": "```text\nregistry/*.yaml   →   themes/*.yaml   →   nons CLI   →   your app\n(اولیهٔ خام)           (نگاشت نقش)         (تولید CSS)     (مصرف متغیرها)\n```\n\n* **Registry** = مقادیر اولیهٔ خام و بدون‌نام (رنگ‌های OKLCH، اندازه‌های `fs-*`، فاصله‌گذاری…).\n* **Theme** = نقش‌های معنایی را به اولیه‌ها نگاشت می‌کند (هرگز مقدار خام را ذخیره نمی‌کند).\n* **CLI (`nons`)** = YAML را به CSS Custom Property برای استک شما تبدیل می‌کند.\n* **App شما** = متغیرهای CSS تولیدشده را مصرف می‌کند. **هرگز مقدار خام را مستقیماً ننویسید.**"
    },
    {
      "level": 3,
      "heading": "قانون طلایی",
      "content": "> به یک توکن ارجاع بده. هرگز یک مقدار خام `px`، `oklch(...)`، هگز یا وزن عددی را در کد محصول\n> ننویس. اگر مقدار موردنیازت وجود ندارد، آن را به Registry اضافه کن — به‌صورت درون‌خطی (inline) قرارش نده.\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. واژگان توکن‌های خروجی CLI",
      "content": "مصرف‌کننده با **CSS Custom Property** کار می‌کند. نام‌های زیر متغیرهای تولیدشده هستند؛ مقادیر از Registry/تم می‌آیند و به‌صورت خودکار بین light/dark جابه‌جا می‌شوند."
    },
    {
      "level": 3,
      "heading": "۲.۱ رنگ‌ها — معنایی (surface / text / border)",
      "content": "| متغیر | معنی |\n|----------|---------|\n| `--bg-primary` | پس‌زمینهٔ اصلی برنامه |\n| `--bg-sidebar` | پس‌زمینهٔ نوار کناری / ناوبری |\n| `--bg-card` | سطح کارت / پنل |\n| `--bg-hover` | سطح hover خنثی |\n| `--text-primary` | متن پیش‌فرض |\n| `--text-secondary` | متن کمرنگ / ثانویه |\n| `--border-primary` | حاشیهٔ پیش‌فرض، همچنین پرکنندهٔ حالت غیرفعال |\n| `--overlay-bg` | سایهٔ مُدال / کشو |"
    },
    {
      "level": 3,
      "heading": "۲.۲ رنگ‌ها — برند و وضعیت",
      "content": "| متغیر | معنی |\n|----------|---------|\n| `--color-primary` | سبز برند (عنصر توپر، filled) |\n| `--color-primary-hover` | سبز توپر ~۸٪ تیره‌تر (hover توپر) |\n| `--color-primary-active` | سبز توپر ~۱۶٪ تیره‌تر (فشردهٔ pressed) |\n| `--color-primary-bg` | ۱۵٪ رنگ سبز (پس‌زمینهٔ انتخاب‌شده) |\n| `--color-primary-selected-bg` | ۸٪ رنگ سبز (پس‌زمینهٔ hover) |\n| `--color-primary-dark` | سبز تیره (متن/آیکون روی سبز) |\n| `--color-danger` / `--color-danger-bg` | fg / bg خطا |\n| `--color-success` / `--color-success-bg` | fg / bg موفقیت |\n| `--color-warning` / `--color-warning-bg` | fg / bg هشدار |\n| `--color-info` / `--color-info-bg` | fg / bg اطلاعات |"
    },
    {
      "level": 3,
      "heading": "۲.۳ تایپوگرافی",
      "content": "توکن‌های اولیه (`registry/typography.yaml`): `--fs-*` (اندازه)، `--fw-*` (وزن)،\n`--lh-*` (ارتفاع خط)، `--ls-*` (فاصلهٔ حروف)، `--ff-*` (خانواده). محصولات آن‌ها را از\nطریق **توکن‌های نقش** تعریف‌شده در هر تم (`typography.roles`) مصرف می‌کنند؛ مثلاً\n`title.lg`، `body.md`، `button.md`، `caption.md`. برای قانون سلسله‌مراتب و مقیاس هر محصول\nبه [تایپوگرافی](typography) مراجعه کنید.\n\n| پیشوند | مثال | مقدار |\n|--------|---------|-------|\n| `--fs-*` | `--fs-14` | `14px` |\n| `--fw-*` | `--fw-semibold` | `600` |\n| `--lh-*` | `--lh-1-5` | `1.5` |\n| `--ls-*` | `--ls-n15` | `-0.015em` |\n| `--ff-*` | `--ff-primary` | پشتهٔ فونت |"
    },
    {
      "level": 3,
      "heading": "۲.۴ سایر رجیستری‌ها",
      "content": "| رجیستری | متغیرها | نمونه |\n|----------|-----------|--------|\n| spacing | `--ds-spacing-*` | `--ds-spacing-4 = 16px` |\n| radius | `--ds-radius-*` | `--ds-radius-md = 8px` |\n| shadow | `--ds-shadow-*` | `--ds-shadow-md` |\n| motion | `--ds-motion-duration-*`, `--ds-motion-easing-*` | `fast = 150ms` |\n| border | `--ds-border-width-*` | `default = 1px` |\n| opacity | `--ds-opacity-*` | `disabled = 0.5` |\n| z-index | `--ds-z-index-*` | `modal = 1000` |\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. حالت روشن / تاریک (Light / Dark)",
      "content": "CLI هر دو تم را تولید می‌کند؛ با تنظیم یک attribute روی ریشه جابه‌جا می‌شوند:\n\n```html\n<html data-theme=\"light\"> … </html>\n<!-- تغییر به -->\n<html data-theme=\"dark\"> … </html>\n```\n\nتمام متغیرهای `--bg-*`، `--text-*`، `--color-*-bg`، `--border-*` به‌صورت خودکار به مقدار\nدرست در هر حالت رفع می‌شوند. **شما قوانین رنگی وابسته به حالت نمی‌نویسید** — فقط توکن را\nمی‌نویسید. تنها استثنا رنگ متن روی یک سطح سبز است (به §۵.۱ مراجعه کنید).\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. حالت‌های تعاملی (مهم‌ترین بخش)",
      "content": "**دو الگوی متفاوت** وجود دارد. آن‌ها را با هم قاطی نکنید."
    },
    {
      "level": 3,
      "heading": "۴.۱ عنصر اولیهٔ توپر (دکمه) — توپر، تیره‌تر در hover/active",
      "content": "```css\n.btn-primary            { background: var(--color-primary);        color: var(--color-primary-dark); }\n.btn-primary:hover      { background: var(--color-primary-hover); }   /* توپر، ~۸٪ تیره‌تر */\n.btn-primary:active     { background: var(--color-primary-active); }  /* توپر، ~۱۶٪ تیره‌تر */\n```\n\nیک عنصر توپر باید از توکن‌های **تیرهٔ توپر** استفاده کند. هرگز برای hover توپر از یک tint\nشفاف استفاده نکن — در حالت تاریک محو می‌شود."
    },
    {
      "level": 3,
      "heading": "۴.۲ پس‌زمینهٔ آیتم انتخاب‌شده (nav / tab / menu) — tint برند + تاکید",
      "content": "```css\n.nav-item                       { color: var(--text-primary); }\n.nav-item:hover                 { background: var(--bg-hover); }              /* خنثی */\n.nav-item[aria-current=\"page\"]  { background: var(--color-primary-bg);       /* ۱۵٪ tint */\n                                   color: var(--color-primary-dark); font-weight: var(--fw-semibold); }\n.nav-item[aria-current=\"page\"]::before {   /* نوار تاکید توپر = \"انتخاب‌شده\" بدون ابهام */\n  content:\"\"; position:absolute; inset-inline-start:0; top:8px; bottom:8px;\n  width:3px; border-radius:3px; background: var(--color-primary);\n}\n```"
    },
    {
      "level": 3,
      "heading": "۴.۳ غیرفعال — سطح خنثی توپر (هرگز opacity روی یک tint)",
      "content": "```css\n.btn:disabled, .btn:disabled:hover {\n  background: var(--border-primary);   /* خنثی توپر، در هر دو حالت مرئی */\n  color: var(--text-secondary);\n  border-color: transparent; cursor: not-allowed;\n}\n```\n\nاز **ویژگی‌های وضعیت** (`[aria-current]`، `[aria-selected]`، `[aria-disabled]`،\n`:hover`، `:active`، `:disabled`) استفاده کن — نه کلاس‌های مبهم `is-active`.\n\nماتریس کامل و منطق: [حالت‌های تعاملی](interactive-states).\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. بازتولید رابط کاربری مرجع",
      "content": "در ادامه الگوهای دقیق پشت `preview/index.html` آمده است. آن‌ها را کپی کنید؛ توکن‌ها را\nجابه‌جا کنید، هرگز مقادیر را."
    },
    {
      "level": 3,
      "heading": "۵.۱ App shell + ناوبری کناری",
      "content": "```css\nbody        { background: var(--bg-primary); color: var(--text-primary); font-family: var(--ff-primary); }\n.sidebar    { background: var(--bg-sidebar); border-right: 1px solid var(--border-primary); }\n.page-title { font-size: var(--fs-22); font-weight: var(--fw-semibold); letter-spacing: var(--ls-n15); }\n```\n\n> متن ناوبری انتخاب‌شده در حالت روشن از `--color-primary-dark` و در حالت تاریک از\n> `--text-primary` استفاده می‌کند (کنتراست روی tint متفاوت است). این تنها جایی است که بر اساس\n> تم شاخه‌بندی می‌کنید."
    },
    {
      "level": 3,
      "heading": "۵.۲ کارت + KPI",
      "content": "```css\n.card { background: var(--bg-card); border: 1px solid var(--border-primary); border-radius: var(--ds-radius-lg); }\n.card h3  { font-size: var(--fs-15); font-weight: var(--fw-semibold); letter-spacing: var(--ls-n5); }\n.card .sub{ font-size: var(--fs-12); color: var(--text-secondary); }\n.kpi      { font-size: var(--fs-30); font-weight: var(--fw-semibold); letter-spacing: var(--ls-n20); }\n```"
    },
    {
      "level": 3,
      "heading": "۵.۳ فیلد فرم",
      "content": "```css\n.label  { font-size: var(--fs-13); font-weight: var(--fw-medium); }\n.input  { background: var(--bg-card); color: var(--text-primary); border: 1px solid var(--border-primary);\n          border-radius: var(--ds-radius-md); font-size: var(--fs-14); }\n.input::placeholder { color: var(--text-secondary); }\n.input:focus { border-color: var(--color-primary); box-shadow: 0 0 0 3px var(--color-primary-bg); }\n.hint   { font-size: var(--fs-12); color: var(--text-secondary); }\n```"
    },
    {
      "level": 3,
      "heading": "۵.۴ تب‌ها",
      "content": "```css\n.tab                     { font-size: var(--fs-13); font-weight: var(--fw-medium); color: var(--text-secondary); border-bottom: 2px solid transparent; }\n.tab:hover               { color: var(--text-primary); }\n.tab[aria-selected=\"true\"]{ color: var(--color-primary-dark); border-bottom-color: var(--color-primary); }\n```"
    },
    {
      "level": 3,
      "heading": "۵.۵ هشدارها",
      "content": "```css\n.alert-danger  { background: var(--color-danger-bg);  color: var(--color-danger); }\n.alert-success { background: var(--color-success-bg); color: var(--color-success); }\n.alert-warning { background: var(--color-warning-bg); color: var(--color-warning); }\n.alert-info    { background: var(--color-info-bg);    color: var(--color-info); }\n```\n\n`preview/index.html` را در مرورگر باز کنید و بین light/dark جابه‌جا شوید تا نتیجهٔ کامل را ببینید.\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. انجام دهید / انجام ندهید",
      "content": "| ✅ انجام دهید | ❌ انجام ندهید |\n|------|---------|\n| `background: var(--color-primary)` | `background: oklch(0.857 0.17 134.6)` |\n| `font-size: var(--fs-14)` | `font-size: 14px` |\n| hover توپر → `--color-primary-hover` | hover توپر → یک tint شفاف |\n| غیرفعال → `--border-primary` توپر + متن کمرنگ | غیرفعال → `opacity` روی یک tint |\n| اضافه کردن مقدارِ گم‌شده به Registry | قرار دادن in-place یک مقدار یک‌بار مصرف در کامپوننت |\n| تغییر تم از طریق `data-theme` | نوشتن قوانین رنگی جداگانه برای حالت تاریک |\n| استفاده از `[aria-current]` / `[aria-selected]` | فقط استایل بی‌معنای `.active` |\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. دریافت توکن‌ها",
      "content": "```powershell"
    },
    {
      "level": 1,
      "heading": "ویندوز",
      "content": "$env:NONS_GITHUB_TOKEN = \"ghp_...\"\n.\\nons.ps1 init\n.\\nons.ps1 sync\n```\n\n```bash"
    },
    {
      "level": 1,
      "heading": "macOS / Linux",
      "content": "export NONS_GITHUB_TOKEN=ghp_...\nnons init\nnons sync\n```\n\nتوکن‌ها در `.nons/system-design/` (رجیستری + تم‌ها + فونت‌ها) قرار می‌گیرند. `manifest.json`\nمنبع حقیقت برای رجیستری‌های موجود، تم‌ها، نسخه‌ها و `colorGuide` خوانا برای انسان است."
    }
  ]
}