המרת Design System לספריית קומפוננטות — צעד אחר צעד

מ-Design System בפיגמה לספריית קומפוננטות בקוד

ה-Design System שלכם בפיגמה הוא נכס עסקי. הוא מגדיר את השפה הויזואלית של המוצר, מבטיח עקביות בין מסכים, ומאפשר לצוות העיצוב לעבוד מהר. אבל כדי שהוא באמת ישרת את המוצר, הוא צריך להתקיים גם בקוד — כספריית קומפוננטות שהמפתחים משתמשים בה ביומיום.

המדריך הזה מפרט את התהליך המדויק שאנחנו עוברים כשממירים Design System מפיגמה לספריית React. לא עקרונות כלליים — שלבים מעשיים עם דוגמאות קוד.

שלב 1: חילוץ וארגון Tokens

הצעד הראשון הוא לחלץ את כל ה-tokens מפיגמה ולהפוך אותם למשתני CSS או Tailwind config. Tokens הם הבסיס — כל קומפוננטה תתייחס אליהם במקום לערכים קשיחים:

// tokens/colors.ts
export const colors = {
  primitive: {
    blue: {
      50: '#EFF6FF',
      100: '#DBEAFE',
      500: '#3B82F6',
      600: '#2563EB',
      900: '#1E3A5F',
    },
  },
  semantic: {
    primary: 'var(--color-blue-600)',
    'primary-hover': 'var(--color-blue-700)',
    background: 'var(--color-white)',
    'text-primary': 'var(--color-gray-900)',
    'text-secondary': 'var(--color-gray-600)',
    error: 'var(--color-red-500)',
    success: 'var(--color-green-500)',
  },
} as const;

חשוב להפריד בין primitive tokens (ערכים גולמיים כמו blue-500) ל-semantic tokens (משמעויות כמו color-primary). הקומפוננטות צריכות להשתמש רק ב-semantic tokens — כך שינוי ערכת צבעים או dark mode דורש שינוי במקום אחד בלבד.

שלב 2: קומפוננטות Primitive

Primitives הם אבני הבניין הקטנות ביותר — Button, Input, Badge, Avatar, Icon. כל primitive מקבל typed props שמשקפים את ה-variants בפיגמה:

// components/Button/Button.tsx
interface ButtonProps {
  variant: 'primary' | 'secondary' | 'ghost' | 'danger';
  size: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
  isDisabled?: boolean;
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
  children: React.ReactNode;
}

export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  isLoading,
  isDisabled,
  leftIcon,
  rightIcon,
  children,
  ...rest
}) => {
  // implementation
};

כל prop מתמפה ל-variant בפיגמה. variant=primary בקוד = Variant=Primary בפיגמה. המיפוי צריך להיות 1:1 — אם המעצב מוסיף variant חדש בפיגמה, המפתח מוסיף ערך ל-union type.

שלב 3: קומפוננטות Composite

Composites הם קומפוננטות שמורכבות מכמה primitives — Card, Modal, Dropdown, Table. כאן הארכיטקטורה נהיית קריטית:

• Compound Components Pattern: במקום props שטוחים, משתמשים ב-sub-components: <Card><Card.Header/><Card.Body/><Card.Footer/></Card>. זה משקף את מבנה הקומפוננטה בפיגמה ונותן גמישות.
• Slot Pattern: קומפוננטות עם "חורים" שאפשר למלא — startSlot, endSlot, headerAction. מאפשר שימוש חוזר בלי props מורכבים.
• Controlled vs. Uncontrolled: כל קומפוננטה עם state פנימי (Accordion, Tabs, Modal) תומכת גם במצב controlled (ה-parent שולט) וגם uncontrolled (ניהול עצמי). זה מאפשר שימוש פשוט וגם שליטה מלאה.

שלב 4: תיעוד Storybook

Storybook הוא הגשר בין מעצבים למפתחים. כל קומפוננטה מקבלת:

• Stories לכל variant ומצב: Primary, Secondary, Ghost, Disabled, Loading, With Icons — כל שילוב שקיים בפיגמה קיים גם ב-Storybook.
• Controls אינטראקטיביים: המעצב יכול לשנות props בזמן אמת ולראות את התוצאה — בלי לכתוב קוד.
• Design Tokens דוקומנטציה: עמוד ייעודי שמציג את כל ה-tokens — צבעים, ריווח, טיפוגרפיה, צללים — עם הערכים בפיגמה לצד הערכים בקוד.
• Usage Guidelines: מתי להשתמש ב-Primary Button ומתי ב-Secondary? מה הגודל המומלץ למובייל? הנחיות שימוש שנכתבות בשיתוף עם צוות העיצוב.

שלב 5: בדיקות ואימות

ספריית קומפוננטות בלי בדיקות היא ספרייה שתישבר. שלושה סוגי בדיקות הם חובה:

• Unit Tests: כל קומפוננטה עם בדיקות לכל variant, מצב ו-edge case. "Button disabled לא מפעיל onClick", "Input error מציג הודעת שגיאה", "Modal נסגר ב-Escape".
• Visual Regression Tests: Chromatic או Playwright screenshots שמשווים את הרינדור בקוד לעיצוב בפיגמה. כל שינוי שמשפיע על הרינדור — מקבל alert אוטומטי.
• Accessibility Tests: axe-core אוטומטי על כל story ב-Storybook. בדיקת WCAG 2.1 AA — contrast ratios, ARIA labels, keyboard navigation, focus management.

שלב 6: Versioning ו-Distribution

ספרייה שמשתנה בלי גרסאות שוברת מוצרים. אנחנו מגדירים:

• Semantic Versioning: patch לתיקוני באגים, minor לפיצ׳רים חדשים, major ל-breaking changes.
• Changelog אוטומטי: מ-conventional commits — כל שינוי מתועד אוטומטית.
• NPM Package פנימי: הספרייה מתפרסמת כ-package שכל פרויקט יכול להתקין. לא copy-paste של קבצים.

הטעות שכולם עושים

הטעות הנפוצה ביותר: לנסות לבנות את כל הספרייה לפני שמשתמשים בה. הגישה הנכונה היא לבנות איטרטיבית — להתחיל עם 5-10 קומפוננטות שהמוצר צריך עכשיו, לשלב אותן בקוד אמיתי, לקבל פידבק, ואז להרחיב. ספרייה שנבנתה בוואקום תמיד דורשת refactor כבד כשפוגשת את המציאות.

רוצים שנעזור לכם להמיר את ה-Design System שלכם לספריית קומפוננטות? קבעו שיחת ייעוץ טכני חינם ונתכנן יחד את הארכיטקטורה.