{
  "title": "توکن‌های حالت تعاملی — راهنمای مصرف‌کننده",
  "slug": "team/frontend/design-system/interactive-states",
  "url": "/docs/team/frontend/design-system/interactive-states",
  "frontmatter": {
    "layout": "doc",
    "title": "توکن‌های حالت تعاملی (Interactive States)",
    "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": "**Interactive State Tokens — Consumer Guide**\n\nنحوهٔ استفاده از **لایهٔ توکن حالت** (state token layer) سیستم طراحی در یک پروژهٔ مصرف‌کننده.\nخود توکن‌ها در این مخزن تعریف شده‌اند (`themes/*/yaml → semantic.{light,dark}.interactive`)؛\nاین فایل توضیح می‌دهد که یک مصرف‌کننده چگونه آن‌ها را اعمال کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "فهرست محتوا",
      "content": "1. [چه چیزی اضافه شد (در این مخزن)](#چه-چیزی-اضافه-شد-در-این-مخزن)\n2. [واژگان توکن → منبع](#واژگان-توکن--منبع)\n3. [نحوهٔ اعمال حالت‌ها توسط مصرف‌کننده](#نحوهٔ-اعمال-حالت‌ها-توسط-مصرف‌کننده)\n4. [وابستگی به CLI (پیگیری GAP-REPORT)](#وابستگی-به-cli-پیگیری-gap-report)\n\n---"
    },
    {
      "level": 2,
      "heading": "چه چیزی اضافه شد (در این مخزن)",
      "content": "هر تم اکنون یک بلاک معنایی `interactive` نمایش می‌دهد — یک ماتریس **نقش × حالت** که فقط به\nاولیه‌های موجود در Registry ارجاع می‌دهد. حالت‌ها فراگیر هستند (نه به‌ازای هر کامپوننت)، پس\n`nav`، `tab`، `menu` و `button` همگی توکن‌های یکسانی دارند.\n\n```yaml\nsemantic:\n  light:\n    interactive:\n      primary:    { default, hover, active, disabled }  # عنصر اولیهٔ FILLED (دکمه): توپر، تیره‌تر در hover/active\n      selection:  { hover, active }                      # پس‌زمینه آیتم SELECTED (nav/tab/menu): tint برند\n      surface:    { hover, disabled }                    # hover سطح خنثی؛ غیرفعال = پرکنندهٔ خنثی توپر\n      text:       { default, disabled }\n  dark:\n    interactive:   # شکل یکسان، نگاشت‌های اولیهٔ متفاوت\n```"
    },
    {
      "level": 3,
      "heading": "واژگان توکن → منبع",
      "content": "| توکن (CSS var) | نقش | حالت | اولیهٔ منبع |\n|-----------------|------|-------|------------------|\n| `--color-primary` | primary | default (filled) | `primitive.primary.default` (سبز توپر) |\n| `--color-primary-hover` | primary | **hover** | `primitive.primary.hover` (توپر، ~۸٪ تیره‌تر) |\n| `--color-primary-active` | primary | **active/pressed** | `primitive.primary.active` (توپر، ~۱۶٪ تیره‌تر) |\n| `--border-primary` | primary/surface | disabled | `primitive.border` (خنثی توپر) |\n| `--color-primary-selected-bg` | selection | hover | `primitive.primary.selectedBg` (۸٪ tint) |\n| `--color-primary-bg` | selection | active/selected | `primitive.primary.bg` (۱۵٪ tint) |\n| `--bg-hover` | surface | hover (خنثی) | `primitive.ui.hover` |\n| `--text-primary` / `--text-secondary` | text | default / disabled | `primitive.text.*` (L/D متفاوت) |\n\n**دو الگوی متمایز — آن‌ها را قاطی نکنید:**\n\n1. **عنصر اولیهٔ توپر (دکمه):** سبز توپری که در hover/active **تیره‌تر** می‌شود.\n   `--color-primary` → `--color-primary-hover` → `--color-primary-active`. این‌ها سبزهای\n   تیرهٔ واقعی هستند (نه tint شفاف)، پس hover در **هر دو** حالت روشن و تاریک کاملاً مرئی است.\n   متن همچنان `--color-primary-dark` باقی می‌ماند.\n\n2. **پس‌زمینهٔ آیتم انتخاب‌شده (nav / tab / menu):** یک **tint** برند روی سطح — در hover\n   `--color-primary-selected-bg` (۸٪)، در حالت انتخاب‌شده `--color-primary-bg` (۱۵٪) — به‌علاوهٔ\n   یک نوار تاکید توپر `--color-primary` برای نشانگر بدون ابهام.\n\n**چرا نسخهٔ قبلی اشتباه بود:** یک دکمهٔ اولیهٔ توپر نباید برای hover از یک tint شفاف استفاده\nکند — با شفافیت/opacity در حالت تاریک محو می‌شود. عناصر توپر از `primary.hover` / `primary.active`\nتیرهٔ توپر استفاده می‌کنند؛ فقط پس‌زمینه‌های انتخاب‌شده از tint استفاده می‌کنند.\n\n---"
    },
    {
      "level": 2,
      "heading": "نحوهٔ اعمال حالت‌ها توسط مصرف‌کننده",
      "content": "سیستم طراحی فقط **مقادیر** را ارائه می‌دهد. مصرف‌کننده مالکِ *زمان* فعال‌بودن یک حالت\n(selectorها / attributeها) است و به توکن ارجاع می‌دهد — هرگز به یک رنگ خام.\n\n```css\n/* آیتم ناوبری */\n.navItem {\n  background: transparent;\n  color: var(--text-primary);\n}\n.navItem:hover            { background: var(--bg-hover); }            /* surface.hover (خنثی) */\n.navItem[aria-current=\"page\"] {\n  background: var(--color-primary-bg);          /* primary.active (۱۵٪ tint سبز) */\n  color: var(--color-primary-dark);             /* روشن؛ در تاریک از --text-primary استفاده کن */\n  font-weight: 600;\n  position: relative;\n}\n.navItem[aria-current=\"page\"]::before {         /* نوار تاکید توپر = selected بدون ابهام */\n  content: \"\"; position: absolute; inset-inline-start: 0; top: 8px; bottom: 8px;\n  width: 3px; border-radius: 3px; background: var(--color-primary);\n}\n.navItem[aria-disabled=\"true\"] { color: var(--text-secondary); background: transparent; } /* text.disabled */\n\n/* دکمهٔ غیرفعال توپر — سطح خنثی توپر، نه opacity روی یک tint\n   (opacity روی یک tint شفاف در حالت تاریک محو می‌شود). همچنین hover را متوقف کن. */\n.btn:disabled,\n.btn:disabled:hover {\n  background: var(--border-primary);   /* surface.disabled (خنثی توپر) */\n  color: var(--text-secondary);        /* text.disabled */\n  border-color: transparent;\n  cursor: not-allowed;\n}\n\n/* تب‌ها */\n.tab[aria-selected=\"true\"] { border-bottom: 2px solid var(--color-primary); color: var(--color-primary-dark); }\n\n/* منو */\n.menuItem:hover { background: var(--bg-hover); }\n.menuItem:active { background: var(--color-primary-bg); }   /* primary.hover */\n\n/* دکمهٔ اولیهٔ توپر — توپر، تیره‌تر در hover/active */\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```"
    },
    {
      "level": 3,
      "heading": "قوانین برای مصرف‌کنندگان",
      "content": "* به توکن ارجاع بده؛ هرگز برای یک حالت تعاملی یک OKLCH/هگز را hardcode کن.\n* از ویژگی‌های وضعیت معنایی (`[aria-current]`، `[aria-selected]`، `[aria-disabled]`،\n  `:hover`، `:active`، `:disabled`) استفاده کن — کلاس‌های بی‌معنای `is-active` اختراع نکن که معنا را پنهان می‌کنند.\n* `disabled` برای یک عنصر **توپر** (مثل دکمهٔ اولیه) از `surface.disabled` توپر\n  (`--border-primary`) + `text.disabled` (`--text-secondary`) استفاده می‌کند و باید `:hover`\n  را نیز خنثی کند. **از `opacity` روی یک tint شفاف استفاده نکن** — در حالت تاریک نامرئی می‌شود.\n  برای یک عنصر **فقط‌متنی**، کمرنگ‌کردن رنگ متن کافی است.\n* اگر یک محصول واقعاً به یک سایهٔ active متفاوت نیاز دارد، تم را بسط بده (theme extension) —\n  نام توکن را بازتعریف نکن.\n\n---"
    },
    {
      "level": 2,
      "heading": "وابستگی به CLI (پیگیری GAP-REPORT)",
      "content": "این متغیرهای CSS توسط CLI `nons` از اولیه‌های `registry/colors.yaml` تولید می‌شوند. تا زمانی\nکه CLI نگاشت‌های `interactive.*` را تولید کند (به Gap A در `GAP-REPORT.md` مراجعه کنید)،\nمصرف‌کننده باید به متغیرهای موجودی که پیش‌تر تولید شده‌اند بازگردد (`--color-primary`،\n`--color-primary-bg`، `--color-primary-selected-bg`، `--bg-hover`، `--text-primary`،\n`--text-secondary`) — که همگی هم‌اکنون در Registry وجود دارند."
    }
  ]
}