شروع به کار با «راهنمای وب نوین»

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

نصب

«راهنمای وب نوین» را می‌توان با هر عامل کدنویسی که از مهارت‌ها پشتیبانی می‌کند نصب و استفاده کرد.

‫modern-web-guidance CLI (توصیه‌شده)

روش نصب توصیه‌شده ازطریق modern-web-guidance CLI است که توسط تیم Chrome ساخته شده است. نصب «راهنمای وب نوین» ازطریق modern-web-guidance CLI به‌روزرسانی‌های خودکار را فعال خواهد کرد. می‌توانید از modern-web-guidance CLI به‌این‌صورت نصب کنید:

npx modern-web-guidance@latest install

اختیاراً، اگر درحال توسعه افزونه‌های Chrome هستید، فرمان زیر را توصیه می‌کنیم:

npx modern-web-guidance@latest install --choose

با این کار، جادوگر تعاملی اجرا می‌شود تا مهارت‌ها را براساس اولویت‌های شما نصب کند.

اگر ترجیح می‌دهید «راهنمای وب نوین» را بدون استفاده از modern-web-guidance CLI نصب کنید، به دستورالعمل‌های زیر که مختص عامل است مراجعه کنید. فقط توجه داشته باشید که اکثر این گزینه‌ها از به‌روزرسانی‌های خودکار پشتیبانی نمی‌کنند.

Antigravity

Antigravity را بارگیری کنید و «modern-web-guidance» را درطول جریان نصب یا از صفحه تنظیمات در بخش سفارشی‌سازی‌ها و سپس ساخت با افزایه‌های Google فعال کنید.

Antigravity CLI

agy plugin install https://github.com/GoogleChrome/modern-web-guidance

Gemini CLI

gemini extensions install https://github.com/GoogleChrome/modern-web-guidance --auto-update

JetBrains WebStorm

می‌توانید «راهنمای وب نوین» را در مدیر مهارت پیدا کنید که در تنظیمات > دستیار هوش مصنوعی > مهارت‌ها دردسترس است. مهارتی را انتخاب کنید تا صفحه جزئیات آن باز شود. برای نصب مهارت، روی دکمه نصب کلیک کنید تا آن را روی نمونه IDE فعلی اعمال کنید.

توجه: می‌توانید هدف نصب دیگری را انتخاب کنید که در منو نصب نیز دردسترس است.

GitHub CLI

gh skill install GoogleChrome/modern-web-guidance

npx skills

npx skills add GoogleChrome/modern-web-guidance

Claude Code

claude plugin install modern-web-guidance@claude-plugins-official

Claude Code CLI

نصب «راهنمای وب نوین» برای استفاده با Claude Code CLI سه مرحله دارد:

۱. افزودن بازار:

/plugin marketplace add GoogleChrome/modern-web-guidance

۲. افزایه را از بازارگاه نصب کنید:

/plugin install modern-web-guidance@googlechrome

3. مجدد بار کردن افزایه‌ها:

/reload-plugins

کدکس

codex plugin marketplace add GoogleChrome/modern-web-guidance
codex plugin add modern-web-guidance@googlechrome

Copilot CLI

نصب «راهنمای وب نوین» برای استفاده با Copilot دو مرحله دارد:

۱. افزودن بازار:

/plugin marketplace add GoogleChrome/modern-web-guidance

۲. افزایه را از بازارگاه نصب کنید:

/plugin install modern-web-guidance@googlechrome

غاز

goose plugin install https://github.com/GoogleChrome/modern-web-guidance --auto-update

Grok

grok plugin install https://github.com/GoogleChrome/modern-web-guidance --trust

کد کیمی

/plugins install https://github.com/GoogleChrome/modern-web-guidance

کاوش کردن قبل‌از نصب

قبل‌از نصب، کتابخانه راهنمای «راهنمای وب نوین» را با جستجوی پُرسمان یا بازیابی راهنماهای ما براساس شناسه ارزیابی کنید. برای انجام این کار، از فرمان search در CLI استفاده کنید تا شناسه مورد استفاده را بااستفاده از پیام‌واره پیدا کنید:

npx modern-web-guidance@latest search "animate a dialog modal backdrop"

با این کار، یک شیء JSON در پایانه شما خروجی داده می‌شود:

[{"id":"light-dismiss-a-dialog","description":"Create a modal dialog that can be closed via light dismiss (i.e. clicking or tapping outside of the dialog)","category":"ui-behaviors","featuresUsed":["<dialog closedby>"],"tokenCount":1085,"similarity":0.7076},
{"id":"animate-to-from-top-layer","description":"Animate elements such as dialogs, popovers, and tooltips as they're entering/exiting the top layer.","category":"ui-behaviors","featuresUsed":["::backdrop","<dialog>","overlay","Popover","@starting-style","transition-behavior"],"tokenCount":1541,"similarity":0.6842},
{"id":"declarative-dialog-popover-control","description":"Toggle the visibility of a dialog or popover from a button without writing JavaScript.","category":"ui-behaviors","featuresUsed":["Invoker commands","Popover","<dialog>"],"tokenCount":2684,"similarity":0.5685},
{"id":"html","description":"Action-oriented guidelines for modern HTML architecture, semantics, native interactive APIs (Dialog, Popover, Details), focus management, and resource prioritization. Use this guide when structuring web documents, implementing native overlays, or optimizing resource loading order.","category":"html","tokenCount":5484,"similarity":0.5471},
{"id":"accessibility","description":"Actionable coding guidelines for building accessible web applications, covering semantic HTML, focus management, forms, media, and testing. Use this skill when auditing or implementing accessibility features, keyboard navigation, or ARIA.","category":"accessibility","tokenCount":7129,"similarity":0.5102}]

با خواندن مقادیر description، می‌توانید id را که به بهترین نحو هدف شما را منعکس می‌کند انتخاب کنید و از فرمان retrieve استفاده کنید:

npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

دراین‌صورت، راهنمای Markdown برای مورد استفاده animate-to-from-top-layer در پایانه نمایش داده خواهد شد. برای راهنماهای دیگر، animate-to-from-top-layer را با هر شناسه راهنمای معتبری جایگزین کنید.

چرا باید از «راهنمای وب نوین» استفاده کرد؟

«راهنمای وب نوین» به‌سه دلیل متمایز نسبت‌به مدل‌های هوش مصنوعی بدون کمک، برای توسعه‌دهنده وب مزیت دارد:

1. عامل‌های کدنویسی هوش مصنوعی معمولاً به‌طور پیش‌فرض از راه‌حل‌های قدیمی و منسوخ برای مشکلات توسعه وب مدرن استفاده می‌کنند. این راه‌حل‌ها اغلب حاوی جاوا اسکریپت هستند تا عملکردی را برای مشکلاتی ارائه دهند که با CSS مدرن و میاناهای برنامه‌سازی کاربردی HTML بهتر حل می‌شوند.
2. مدل‌های هوش مصنوعی از گذشته تاکنون از جدیدترین ویژگی‌های پلاتفرم وب آگاه نبوده‌اند یا اطلاعات نادرستی درباره آن‌ها داشته‌اند.
3. درنهایت، مدل‌های هوش مصنوعی معمولاً توصیه‌های قدیمی ارائه می‌دهند که الزامات پروژه یا معیارهای پشتیبانی مرورگر را درنظر نمی‌گیرند، به‌جای اینکه راهنمایی را با الزامات Baseline پروژه موردنظر تطبیق دهند.

«راهنمای وب نوین» این کاستی‌ها را برطرف می‌کند و تضمین می‌کند که گردش کار کدنویسی با کمک هوش مصنوعی شما ابزارهایی برای پذیرش ویژگی‌های جدیدتر پلاتفرم وب در وهله اول و با درنظر گرفتن جایگزین‌ها دارد.

«راهنمای وب نوین» شامل چه چیزهایی است؟

«راهنمای وب نوین» شامل روال‌های مطلوب برای بیش‌از ۱۰۰ مورد استفاده توسعه وب در چندین رشته اصلی است. در پشت صحنه، این یک مهارت عامل است که به عامل کدنویسی شما دستور می‌دهد چگونه modern-web-guidance CLI را فراخوانی کند تا بهترین راهنمایی را برای مورد استفاده شما پیدا و بازیابی کند.

• تجربه کاربری: انتقال‌های نما، سبک‌بندی scrollbar-color CSS، و پویانمایی‌های ورود و خروج.
• CSS: پُرسمان‌های محفظه، فضاهای رنگی مدرن مانند oklch، طرح‌بندی زیرشبکه CSS،‏ text-wrap، و برش ارتفاع خط تایپوگرافی.
• عملکرد: تشخیص «تعامل تا ترسیم بعدی» (INP)، scheduler.yield برای تقسیم کردن کارهای طولانی، زمان‌بندی کارهای پس‌زمینه، و اولویت‌بندی بار کردن تصویر.
• فرم‌ها: فیلدهای ورودی با اندازه خودکار (field-sizing: content)، و سبک‌های اعتبارسنجی دقیق با :user-invalid.
• مؤلفه‌های واسط کاربر داخلی: کنترل مستقیم روی کادرهای گفتگو، CSS Anchor Positioning برای نکته‌ابزارها، و popover.
• دسترس‌پذیری: اعلامیه‌های خطای دسترس‌پذیر و مدیریت تمرکز صفحه‌کلید.
• هوش مصنوعی داخلی: از مدل‌های کارخواه محلی و درون‌دستگاهی (میاناهای برنامه‌سازی کاربردی «تشخیص زبان»، «خلاصه‌سازی»، و «ترجمه» بومی) استفاده کنید.
• گذرکلیدها: ثبت، اصالت‌سنجی، و مدیریت گذرکلید.

این‌ها چند راهنما از هر دسته هستند. برای دیدن همه راهنماها، می‌توانید فهرست کامل راهنماها را مشاهده کنید.

پایه

Baseline به توسعه‌دهندگان کمک می‌کند تا به‌وضوح بدانند کدام ویژگی‌های وب در موتورهای اصلی مرورگر هم‌کنش‌پذیر هستند. اگر ویژگی وب Baseline باشد، می‌توانید به سطح سازگاری مرورگر اعتماد کنید. ویژگی‌های وب در یکی از سه دسته تعریف‌شده توسط Baseline قرار می‌گیرند:

• دسترسی محدود یعنی ویژگی هم‌کنش‌پذیر نیست.
• به‌تازگی دردسترس قرارگرفته یعنی این ویژگی اخیراً در ۳۰ ماه گذشته هم‌کنش‌پذیر شده است.
• به‌طور گسترده دردسترس است یعنی این ویژگی حداقل ۳۰ ماه یا بیشتر هم‌کنش‌پذیر بوده است.

درحالی‌که Baseline تعریفی برای هم‌کُنش‌پذیری ویژگی‌های وب است، جنبه‌ای قابل‌پیکربندی از پروژه شما نیز هست. می‌توانید هدف Baseline را انتخاب کنید، سپس پروژه‌تان را پیکربندی کنید تا با افزودن آن به فایل AGENTS.md یا CLAUDE.md از آن استفاده کند، برای مثال:

This project's Baseline target is Baseline 2024.

<other project info...>

مهم: اگر «راهنمای وب نوین» را نصب کنید اما هدف «خط مبنا» را برای پروژه‌تان پیکربندی نکنید، «راهنمای وب نوین» به‌طور پیش‌فرض روی «خط مبنای به‌طور گسترده دردسترس» تنظیم می‌شود.

راهنمای وب نوین و جایگزین‌های ویژگی

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

چگونه از دقت اطمینان حاصل می‌شود؟

هر مورد استفاده در «راهنمای وب نوین» شامل مجموعه‌ای از ارزیابی‌ها است که به‌طور مداوم کالیبره می‌شوند تا از کیفیت خروجی اطمینان حاصل شود.

ارزیابی‌های مورد استفاده یک مهار تضمین کیفیت خودکار را برای آزمایش رفتار صحیح عامل اجرا می‌کنند، که در آن Playwright نقش محوری ایفا می‌کند:

1. برای هر راهنما، یک اسکریپت Playwright توسعه داده می‌شود تا آزمایش کند که آیا جزئیات پیاده‌سازی راهنما دنبال شده است یا نه—برای مثال، آیا @media (prefers-reduced-motion: reduce) در جایی که الزامی است رعایت شده است یا نه.
2. این اسکریپت‌های Playwright به‌طور مداوم با یک پیاده‌سازی نمایشی مرجع «صحیح» که انتظار نرخ قبولی ۱۰۰٪ دارد، کالیبره می‌شوند. در طرف دیگر، اسکریپت‌ها دربرابر پیاده‌سازی عامدانه ناقصی که انتظار نرخ قبولی ۰٪ دارد بررسی می‌شوند.
3. اگر یکی یا هر دو پیاده‌سازی «صحیح» و عمداً ناقص نتوانند به‌ترتیب نرخ قبولی ۱۰۰٪ و ۰٪ تولید کنند، تولیدکننده به‌طور خودکار بااستفاده از بافت دوباره امتحان می‌کند تا کالیبراسیون ۱۰۰٪ حاصل شود.
4. درنهایت، ارزیابی‌های سرتاسری روی برنامه پایه اعمال می‌شود. یکی از این ارزیابی‌ها بدون راهنمایی است که کنترلی است که از داده‌های آموزشی پیش‌فرض بدون فراخوانی «راهنمای وب نوین» برای تکمیل تکلیف استفاده می‌کند. ارزیابی دیگری (آزمایش) بااستفاده از «راهنمای وب نوین» به همان تکلیف می‌پردازد.

ارزیابی‌های ما چندین بار در هفته با مدل‌های پیشرفته و عامل‌های کدنویسی اجرا می‌شوند و تصویر واضحی از عملکرد عامل‌ها با و بدون راهنمایی ما ارائه می‌دهند. به‌طور میانگین، نتایج اولیه نشان می‌دهد که وقتی عامل‌ها به «راهنمای وب نوین» مجهز می‌شوند، رعایت روال‌های مطلوب نوین ۳۷ درصد بهبود می‌یابد. بااین‌حال، نتایج شما ممکن است بسته به الزامات پروژه، مدل، پیام‌واره‌هایی که می‌نویسید، و ابزارهای کدنویسی عاملی ترجیحی شما متفاوت باشد.

مراحل بعدی

اکنون نمای کلی‌ای از «راهنمای وب نوین» و پتانسیل آن برای آسان‌تر کردن اتخاذ روال‌های مطلوب وب نوین در گردش کار کدنویسی هوش مصنوعی دارید. اکنون می‌توانید راهنماهای ارائه‌شده توسط «راهنمای وب نوین» را کاوش کنید.