‏هر کامپوننت دیزاین‌سیستمت یه قرارداده

نویسنده با اشاره به سیستمِ uSpec از تیم دیزاین‌سیستم Uber شروع می‌کنه؛ سیستمی که مستندسازیِ کامپوننت‌ها رو خودکار کرده و صفحه‌هایی که قبلاً هفته‌ها طول می‌کشید رو به دقیقه رسونده. یه ایجنت داخل Cursor از طریق Figma Console MCP ساختار واقعی کامپوننت رو می‌خونه و صفحهٔ spec می‌سازه. به گفتهٔ نویسنده، نکتهٔ مهم صرفه‌جویی زمان نیست؛ شرطیه که این رو ممکن می‌کنه: دیزاین‌سیستم Uber اون‌قدر خوب ساختاریافته‌ست که ماشین می‌تونه بخونتش. وقتی ساختار صریحه خروجی دقیقه، وقتی نیست ایجنت یا شکست می‌خوره یا از خودش چیزی می‌سازه.

محور اصلی مقاله مفهوم قرارداد (contract) هست. نویسنده مثال Stripe رو می‌زنه: وقتی یه endpoint رو با پارامتر غلط صدا می‌زنی، فوری خطای بامعنی می‌گیری؛ سیستم اشتباه رو نمی‌پذیره، ردش می‌کنه. دیزاین‌سیستم‌ها هم همین‌جور وعده می‌دن: یه prop به اسم variant وعده می‌ده رفتار بر اساس مقدارش فرق کنه، و یه توکن به اسم color-feedback-critical وعده می‌ده که رنگ به‌طور معنایی به بازخورد بحرانی گره خورده. سؤال اینه که این وعده‌ها به شکلی نوشته شدن که چیزی جز آدم هم بتونه بخوندشون؟

نویسنده تفاوت مستندات و قرارداد رو روشن می‌کنه: مستندات توصیف می‌کنه، قرارداد الزام می‌کنه. صفحهٔ Storybook که می‌گه کِی از variant بحرانی استفاده کن مستنداته؛ ولی یه تایپ که فقط چهار مقدار مجاز رو می‌پذیره قرارداده. ایجنت Storybook رو نمی‌خونه، از روی نمونه‌های داخل کدبیس استنتاج می‌کنه؛ و اگه اون نمونه‌ها ناسازگار باشن خروجی ایجنت هم ناسازگار می‌شه. راه‌حلش تایپ‌کردن propها و گذاشتن یه کامنت JSDoc بالای تعریفه تا راهنمای استفاده به همون‌جایی بره که ایجنت واقعاً می‌خونه:

type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';

interface ButtonProps {
  /** Use 'destructive' only for irreversible actions. */
  variant: ButtonVariant;
  children: React.ReactNode;
  onClick: () => void;
}

نویسنده همین منطق رو به نام‌گذاری توکن‌ها می‌بره: توکنی مثل blue-600 قرارداد نیست چون فقط یه مقدار رو توصیف می‌کنه؛ ولی color-action-primary هدف رو اعلام می‌کنه و color-feedback-critical معنا رو حمل می‌کنه. اشاره می‌کنه که مشخصات DTCG که اکتبر ۲۰۲۵ به اولین نسخهٔ پایدارش رسید، همین ساختار سه‌سطحی (توکن primitive، semantic و component) رو رسمی کرده.

لایهٔ سوم، روابط بین کامپوننت‌هاست. مثال یه Modal رو می‌زنه که طبق مستندات باید همیشه یه ModalFooter داشته باشه، ولی ایجنت که مستندات رو نمی‌خونه footer رو حذف می‌کنه و بعداً تو بازبینی دسترس‌پذیری می‌ترکه. راه‌حل نه مستندات بهتر، بلکه رمزگذاریِ رابطه تو خودِ ساختاره؛ مثلاً با الگوی compound component که Dialog.Footer فقط داخل Dialog معنا داره. نویسنده در پایان یه پلاگین Figma به اسم Anova رو معرفی می‌کنه که کامپوننت رو می‌کاوه و یه فایل دادهٔ فشرده و قطعی می‌سازه که فقط تفاوت‌ها و ترکیب‌های نامعتبر رو ثبت می‌کنه؛ به‌جای دادهٔ خامِ چندمگابایتیِ Figma که پر از نویزه. حرف نهایی اینه: سیستمت همین الان داره وعده می‌ده؛ سؤال اینه که این وعده‌ها به‌قدر کافی روشن نوشته شدن که چیزی جز خودت هم بتونه درست بخوندشون.

نکات کلیدی:

• هر کامپوننت و توکن یه قرارداد می‌ده، نه صرفاً یه راهنما
• مستندات توصیف می‌کنه ولی قرارداد در ساختار الزام می‌کنه؛ ایجنت Storybook رو نمی‌خونه
• تایپ‌کردن propها و کامنت JSDoc، خروجی ایجنت رو قابل‌اعتمادتر می‌کنه
• نام‌گذاریِ معنایی توکن (color-action-primary به‌جای blue-600) مطابق مشخصات DTCG
• رمزگذاری روابط کامپوننت در ساختار (مثل compound component) به‌جای اتکا به مستندات