Design system w małym zespole: jak przenieść zasady projektowania z Figma na realną stronę internetową

Cel design systemu w małym zespole, a nie tylko „ładny plik w Figma”

Design system jako narzędzie redukcji chaosu, nie ozdoba

Design system w małym zespole ma przede wszystkim usuwać chaos i ograniczać ilość decyzji, które trzeba podejmować przy każdym nowym ekranie czy funkcji. Plik w Figma pełen ładnych widoków to dopiero początek. Prawdziwy design system to zestaw powtarzalnych reguł i komponentów, które można konsekwentnie odtwarzać w kodzie bez każdorazowego „interpretowania” designu.

W realiach małego zespołu produktowego design system nie musi być tak rozbudowany jak w dużych korporacjach. Co do zasady wystarczy, że zapewnia spójność interfejsu www i daje programiście jasne odpowiedzi na proste pytania: jakiego fontu użyć, jaki padding w przycisku, jaki kolor dla błędu formularza, jak wygląda focus. Jeśli te odpowiedzi wynikają z jednego źródła prawdy, a nie z kilku sprzecznych makiet, system już spełnia swoje zadanie.

Różnica jest subtelna, ale kluczowa: „ładny plik w Figma” jest celem samym w sobie, natomiast design system Figma jest tylko interfejsem do reguł, które muszą zostać odwzorowane w HTML, CSS i kodzie komponentów.

Najważniejsze składniki realnego design systemu

Kompletny system projektowy w dużej organizacji może zawierać dziesiątki elementów. W małym zespole sens ma tylko to, co da się realnie utrzymać. Zwykle kluczowe składniki są następujące:

• Zasady – ogólne reguły: jakiej siatki używamy, jak wyglądają odstępy, hierarchia nagłówków, zachowanie na mobile.
• Style bazowe – typografia, kolory, spacing, promienie zaokrągleń, cienie. To idealni kandydaci na tokens design system.
• Komponenty UI – przyciski, pola formularzy, karty, modal, nawigacja, alerty. Najlepiej zdefiniowane jako komponenty w Figma i jako biblioteka komponentów React (lub analogiczna w innej technologii).
• Dokumentacja design systemu – opis użycia: kiedy dany komponent jest poprawny, jakie ma stany, jakie są warianty typografii i kolorów.
• Procesy – jak dodaje się nowy komponent, kto zatwierdza zmiany, jak weryfikuje się spójność między Figma a kodem.

Bez tych elementów powstaje system „na papierze”, który szybko się rozjeżdża. Minimalna dokumentacja, nawet w formie jednej strony w Notion lub prostego pliku markdown w repozytorium, zwykle robi ogromną różnicę, bo zatrzymuje improwizację.

Minimalny design system w małym zespole

Mały zespół nie udźwignie od razu rozbudowanej biblioteki komponentów z dziesiątkami wariantów. Najrozsądniejsze podejście to stworzenie wersji 1.0, która obejmuje tylko to, co realnie jest potrzebne w najbliższych miesiącach.

Zwykle rozsądne minimum obejmuje:

• spójny system siatki i breakpointów (desktop / tablet / mobile),
• zdefiniowane style typograficzne (Heading 1–3, Body, Caption, Label),
• spójny system kolorów (primary, secondary, success, warning, error, neutral) z odcieniami i stanami,
• kilka kluczowych komponentów: Button, Input, Select, Checkbox, Radio, Card, Modal, Navbar,
• prosty zestaw tokens dla kolorów, typografii, odstępów i promieni (w Figma + w kodzie).

Z czego można na początku zrezygnować? Zwykle z bardzo szczegółowej mikro-typografii, rozbudowanych patternów (np. tabele z edycją inline), zaawansowanych animacji czy „skomplikowanych” gridów. Najpierw warto opanować fundamenty – jeśli te działają, rozbudowa systemu jest wielokrotnie łatwiejsza.

Oczekiwania a rzeczywistość w małym zespole

W małym zespole produktowym projektanci często marzą o dopieszczonej bibliotece komponentów, a programiści – o skończonych makietach, które „same się kodują”. Rzeczywistość zazwyczaj jest bardziej prozaiczna. Czasu jest mało, priorytetem są funkcje biznesowe, a system UI bywa traktowany jako „ładny dodatek”.

Żeby uniknąć rozczarowania, warto wprost ustalić, że:

• design system będzie rozwijany inkrementalnie, razem z produktem,
• nie wszystkie widoki zostaną od razu przepisane na nowy system,
• projektanci i deweloperzy będą regularnie weryfikować współpraca design dev – co działa, a co jest martwe na papierze,
• każdy nowy feature ma być implementowany już na nowych komponentach, nawet jeśli stare jeszcze żyją obok.

Ten rodzaj uczciwego kontraktu bywa ważniejszy niż sama jakość pierwszej wersji komponentów. Spójność powstaje wtedy krok po kroku, zamiast udawać, że „system istnieje”, podczas gdy w kodzie wszystko jest ad hoc.

Diagnoza stanu w Figma: co jest, a czego brakuje

Spójność makiet: na czym oprzeć audyt

Pierwszy krok przed wdrażaniem design systemu to ocena, na ile aktualne pliki są w ogóle spójne. Chodzi o prostą diagnozę: czy da się z nich zbudować system, czy trzeba je najpierw uporządkować. Analiza zwykle obejmuje kilka poziomów:

• Siatki (gridy) – czy wszystkie główne widoki używają tej samej ilości kolumn, podobnych marginesów i gutterów? Czy mobilne widoki opierają się o jasne breakpointy?
• Typografia – czy nagłówki mają powtarzalne rozmiary i interlinię? Czy teksty bazują na stylach, czy na pojedynczych „local styles” i ręcznie ustawianych fontach?
• Kolory – ile odcieni niebieskiego, szarości czy czerwieni pojawia się w plikach? Czy są stosowane globalne style kolorów?
• Odstępy (spacing) – czy paddingi, marginesy i gapy między elementami mają powtarzalne wartości (np. 4/8/12/16/24 px), czy każdy ekran ma inne ustawienia?
• Komponenty – czy przyciski, pola formularzy, karty itp. są komponentami Figma, czy „kopiuj-wklej” z drobnymi różnicami?

Jeśli te elementy są w miarę spójne, wdrożenie design systemu do kodu będzie zadaniem porządkowym. Jeśli każdy ekran jest trochę inny, konieczne może być uproszczenie makiet i ich ujednolicenie, zanim w ogóle powstanie sensowna biblioteka komponentów.

Prosty audyt plików Figma krok po kroku

Do audytu nie są potrzebne wyszukane narzędzia. Wystarczy systematyczne przejście przez pliki z użyciem kilku funkcji Figmy:

• Skorzystanie z zakładki Assets i filtrowania po Styles, aby zobaczyć, ile jest styli kolorów i typografii.
• Wyszukanie w warstwach komponentów typu Button, Input, Card i sprawdzenie, czy są używane te same komponenty, czy różne.
• Sprawdzenie, czy w komponentach stosowany jest Auto Layout, czy elementy są ustawione „na sztywno”.
• Analiza warstw na kilku losowo wybranych ekranach pod kątem duplikatów stylów (np. dwa style tekstu z tą samą wielkością, ale inną nazwą).

Taki audyt pozwala szybko wyłapać tzw. „szybkie wygrane”: miejsca, gdzie konsolidacja stylów i komponentów w Figma od razu ułatwi późniejsze mapowanie na CSS i komponenty w kodzie.

Wyszukiwanie „kandydatów na komponenty”

Dobór komponentów do pierwszej wersji design systemu można oprzeć na czystej obserwacji: które elementy powtarzają się na wielu ekranach i jakie ich warianty są realnie używane. Typowe „kandydaty” to:

• przyciski (primary, secondary, ghost, link),
• pola formularzy (input text, textarea, select, checkbox, radio),
• komponenty nawigacyjne (top navbar, sidebar, tabs),
• karty z obrazkiem i tytułem, listy elementów, tabelki,
• modale, dialogi potwierdzeń, toast/alert.

Warto przejść kilkanaście kluczowych ekranów i oznaczać powtarzające się wzory. Często okazuje się, że np. „pięć różnych kart” to w istocie jedna karta z różnymi kombinacjami opcji (z/bez obrazka, z/bez przycisku, z/bez opisu). To podpowiada, jak projektować warianty komponentu w Figma i w kodzie.

Zakres pierwszej iteracji: ograniczenie pola walki

Mały zespół z reguły nie wdroży pełnego systemu na wszystkich widokach od razu. Ustalony z góry zakres pierwszej iteracji pomaga uniknąć przeciążenia. Rozsądny wybór to:

• Strona główna – reprezentuje główne layouty, hero, sekcje z kartami, CTA.
• Kluczowe formularze – rejestracja, logowanie, onboarding, główne akcje w produkcie.
• Nawigacja – header, footer, ewentualnie boczny panel w aplikacji webowej.

Te części systemu zwykle generują najwięcej interakcji i są najbardziej widoczne dla użytkownika. Jeśli tam panuje spójność, inne obszary można stopniowo dostosowywać przy okazji nowych zadań.

Fundamenty jako kontrakt: siatka, typografia, kolor

Siatka i breakpointy jako wspólny język

Stała siatka i jasno zdefiniowane breakpointy to pierwszy prawdziwy „kontrakt” między designem a developmentem. Deweloper musi wiedzieć, czy projekt opiera się na 12-kolumnowym gridzie, jakie są marginesy boczne na desktopie i jak komponenty zachowują się przy określonych szerokościach.

Praktyczne podejście:

• Zdefiniowanie 3–4 breakpointów (np. 360–480 mobile, 768 tablet, 1024 mały desktop, 1280+ duży desktop).
• Zaprojektowanie w Figma siatek dla tych szerokości (np. 4 kolumny mobile, 8 lub 12 desktop) i konsekwentne ich używanie.
• Opisanie w krótkiej notatce: który breakpoint dotyczy jakiego typu urządzeń i kiedy layout się zmienia.

Po stronie front-endu ten kontrakt przekłada się na konfigurację CSS (media queries, np. w SCSS) lub konfigurację w narzędziach typu Tailwind. Kluczowe jest, aby nazwy i wartości były uzgodnione: jeśli w Figma istnieje „desktop 1440”, to w CSS powinien być analogiczny breakpoint, a nie inny zestaw wartości ustawionych na ślepo.

Mapowanie typografii z Figma na klasy i tokens

Typografia jest jednym z najczęstszych źródeł rozbieżności między designem a kodem. Projektanci potrafią użyć kilkunastu kombinacji font size/line height, podczas gdy programiści wolą 5–6 jasno nazwanych stylów. To naturalny konflikt, który można rozwiązać przez standaryzację stylów typograficznych.

W Figma warto zdefiniować:

• Heading 1–3 (H1–H3) – rozmiar, interlinia, waga, odstępy przed/po,
• Body (np. Body/Large, Body/Regular, Body/Small),
• Caption, Label (np. opisy pól, meta-informacje).

Nazwy styli w Figma można od razu zaplanować tak, aby odwzorować je w kodzie. Przykładowo:

• Figma: Type/Heading/H1, Type/Body/Regular
• CSS variables lub utility classes: .text-h1, .text-body, lub tokens --font-size-h1, --line-height-body

W bibliotekach komponentów React nazwy te mogą przełożyć się na propsy (np. <Text variant="body">) lub dedykowane komponenty (<Heading level={1}>). Ważne, aby nazewnictwo było spójne: jeśli w Figma mówimy o „Body/Small”, w kodzie nie powinno się pojawiać „text-description” dla tego samego stylu.

System kolorów: ograniczona paleta, czytelne nazwy

Zbyt duża liczba kolorów w Figma zwykle przekłada się na bałagan w CSS. Dlatego użyteczne jest rozdzielenie kolorów na dwa poziomy:

• Kolory surowe (raw) – np. blue-500, gray-700, które odpowiadają konkretnym wartościom HEX/RGB.
• Kolory semantyczne – np. color-primary, color-success, color-error, color-text-muted.

W Figma można to odzwierciedlić jako dwa zbiory styli: jeden „paleta” (raw), drugi „użycie” (semantic). W kodzie analogicznie – tokens design system mogą mieć poziom bazowy (np. --blue-500) i poziom semantyczny (np. --color-primary = --blue-500).

Design tokens jako pomost między Figma a kodem

Na czym polega „tokenizacja” decyzji projektowych

Design tokens to po prostu nazwane, najmniejsze decyzje projektowe zapisane w formie danych. Zamiast mówić „przycisk ma 16 px paddingu, font 14 px i niebieskie tło #0055FF”, zespół operuje na poziomie nazw: spacing-md, font-size-body, color-primary. Te nazwy stają się wspólnym językiem dla Figmy, CSS i komponentów front-end.

W małym zespole tokeny nie muszą być od razu wdrażane przy użyciu rozbudowanych narzędzi. Kluczowe jest, aby:

• były spójnie nazwane (bez synonimów typu primary-color, main-blue na to samo),
• obejmowały fundamenty (kolor, typografia, spacing, radius, shadow),
• miały jeden „source of truth” (np. plik JSON, Style Dictionary, plik SCSS).

Rodzaje tokenów: od surowych wartości do użyć semantycznych

Struktura tokenów zwykle ma dwa poziomy. Pierwszy to wartości „surowe” (raw), drugi – ich użycia w interfejsie.

• Tokeny bazowe – odpowiadają konkretnym wartościom:
  • kolory: color-blue-500, color-gray-900,
  • typografia: font-size-14, font-weight-600,
  • spacing: spacing-4, spacing-8,
  • radius: radius-sm, radius-full.
• Tokeny semantyczne – opisują rolę w UI:
  • color-background-default, color-text-muted,
  • color-button-primary-bg, color-button-primary-text,
  • spacing-card-padding, spacing-form-field-gap.

W Figma ten podział może być odzwierciedlony przez grupy styli, np. Color/Base/Blue-500 oraz Color/Semantic/Button/Primary. Po stronie kodu te same nazwy przyjmują postać zmiennych CSS albo wpisów w pliku konfiguracyjnym.

Minimalny zestaw tokenów dla małego zespołu

Zespół 2–3-osobowy nie potrzebuje dziesiątek kategorii tokenów. Na start zwykle wystarcza niewielki, ale konsekwentny zestaw:

• Kolory: 5–7 kolorów bazowych (odcienie brandu, szarości) + semantyczne: primary, secondary, success, warning, error, background, text.
• Typografia: rozmiary i wagi używane w zdefiniowanych stylach H1–H3, Body, Caption.
• Spacing: skala powiązana z tym, co faktycznie widać w layoutach, np. 4/8/12/16/24/32.
• Radius: 1–3 wartości (np. 2px, 8px, 9999px dla elementów typu pill).
• Shadow: 1–2 cienie dla kart i modali, zamiast pięciu subtelnych wariantów.

Im mniejszy projekt i zespół, tym bardziej opłaca się zaczynać od minimum. Brakujące tokeny można dodawać przy konkretnych potrzebach, a nie „na wszelki wypadek”.

Przykładowa implementacja tokenów w CSS

Nawet bez dodatkowych narzędzi można wprowadzić prostą warstwę tokenów jako zmienne CSS:

:root {
  /* base */
  --color-blue-500: #2563eb;
  --color-gray-900: #111827;

  --font-size-h1: 32px;
  --font-size-body: 14px;

  --spacing-4: 4px;
  --spacing-8: 8px;

  --radius-sm: 4px;
  --radius-lg: 12px;

  /* semantic */
  --color-primary: var(--color-blue-500);
  --color-text-default: var(--color-gray-900);
  --color-button-primary-bg: var(--color-primary);
  --color-button-primary-text: #ffffff;
}

W komponentach stosuje się potem jedynie tokeny semantyczne, np. var(--color-button-primary-bg), dzięki czemu zmiana koloru brandowego wymaga modyfikacji jednego wpisu, a nie całego kodu.

Synchronizacja tokenów z Figma

Manualne utrzymywanie zgodności między Figma a kodem szybko staje się uciążliwe. Nawet w małym zespole opłaca się choć częściowo zautomatyzować ten proces. Dostępne są różne ścieżki:

• użycie wtyczek Figmy generujących pliki JSON lub CSS ze styli (np. Figma Tokens / Tokens Studio),
• utrzymywanie pliku „prawdy” w repozytorium (JSON/TS/SCSS) i cykliczne porównywanie go z Figma podczas przeglądu designu,
• spisanie w krótkim dokumencie zasad: kto i kiedy zmienia tokeny, jak komunikowana jest zmiana (PR + komentarz przy odpowiednich ekranach w Figma).

Kluczowe jest, aby zmiana tokenu nie była „lokalną decyzją” jednej osoby. Modyfikacja np. spacing-8 może ustawić cały interfejs za ciasno – dlatego dobrze, jeśli w małym zespole takie zmiany przechodzą choćby szybkie omówienie na stand-upie albo krótką notatkę w PR.

Projektowanie komponentów w Figma pod implementację

Myślenie w strukturze: kontenery, treść, warianty

Komponent w Figma, który ma zostać przełożony na kod, powinien być zaprojektowany tak, aby odzwierciedlał realną strukturę DOM. Zamiast pojedynczego „flattenowanego” elementu, sensownie jest wyodrębnić:

• kontener (np. przycisk, karta, navbar),
• elementy wewnętrzne (ikonę, label, opis, badge),
• warstwy przeznaczone na stany (hover, focus, disabled).

Dzięki temu deweloper widzi od razu, że np. przycisk ma osobną warstwę na ikonę po lewej i tekst, a karta składa się z nagłówka, treści i stopki, które w kodzie będą osobnymi blokami.

Auto Layout jako symulator flexboxa

Auto Layout jest w praktyce odpowiednikiem flexboxa. Im lepiej komponenty korzystają z Auto Layout, tym łatwiej przełożyć je na CSS. Dobrym nawykiem jest:

• ustawienie kierunku (row/column) zgodnego z planowanym układem w kodzie,
• używanie gap zamiast „ręcznych” odstępów (łatwe mapowanie na gap w CSS lub space-x/space-y w utility CSS),
• testowanie zachowania komponentu przy zmianie długości tekstu czy obecności/nieobecności ikon,
• unikanie „zakotwiczonych na sztywno” elementów, które w kodzie wymagałyby absolutnego pozycjonowania bez potrzeby.

Jeżeli przycisk w Figma przy dłuższym labelu „pęka” lub zawija się w dziwny sposób, prawdopodobnie podobny problem pojawi się w implementacji. W małym zespole szybciej jest poprawić Auto Layout od razu niż łatać CSS po wdrożeniu.

Warianty komponentu a propsy w kodzie

Warianty w Figma warto projektować z myślą o tym, jakie propsy będzie miał komponent w React czy Vue. Przykładowo, przycisk może mieć:

• variant: primary, secondary, ghost, link,
• size: sm, md, lg,
• state: default, hover, pressed, disabled,
• icon: none, left, right.

W Figma taki komponent może mieć panel wariantów odzwierciedlający dokładnie te właściwości. W kodzie odpowiada temu komponent:

<Button
  variant="primary"
  size="md"
  disabled
  icon="left"
>
  Zapisz
</Button>

Dzięki temu projektant i deweloper posługują się tym samym zestawem pojęć. Zamiast niejednoznacznych opisów w stylu „ten przycisk to chyba taki trochę secondary, ale z innym tłem”, można powiedzieć: „tu chcemy variant="secondary", ale w stanie hover przy nowym tokenie koloru”.

Minimalny zestaw komponentów bazowych

Aby nie ugrzęznąć w projektowaniu wszystkiego naraz, przy pierwszym podejściu do design systemu zwykle wystarcza kilka komponentów bazowych:

• Button – z wariantami (primary/secondary/ghost/link), wielkościami i stanami.
• Input – pole tekstowe z labelką, placeholderem, komunikatem błędu; osobne warianty dla success/error/disabled.
• Select – nawet w uproszczonej wersji, odzwierciedlającej podstawowe interakcje.
• Card – z nagłówkiem, treścią, stopką, opcjonalnym obrazem.
• Modal/Dialog – z tytułem, treścią, przyciskami akcji.
• Navbar i ewentualnie Sidebar – główna nawigacja.

Takie komponenty obejmują większość typowych widoków. Kolejne elementy (tabele, filtry, zaawansowane widżety) można dopisywać, kiedy rzeczywiście pojawi się na nie potrzeba w projekcie.

Dokumentowanie użycia komponentów w Figma

Sama biblioteka komponentów rzadko wystarczy. Żeby ułatwić development, dobrze jest dodać kilka ekranów „guides”, na których komponenty są opisane w kontekście. Może to być prosta strona typu:

• sekcja z przykładami użycia przycisków (primary/secondary w różnych layoutach),
• sekcja z formularzami pokazująca, jak łączyć Input, Select, Checkbox,
• sekcja z zestawami kart, modali, alertów w realnych scenariuszach.

Deweloper, patrząc na taki ekran, widzi od razu nie tylko pojedynczy komponent, ale całe „klocki LEGO” w praktycznym użyciu. Zmniejsza to liczbę pytań przy implementacji i ułatwia konsekwentne decyzje, gdy czegoś zabraknie w specyfikacji.

Przekład komponentów z Figma na front-end

Od komponentu wizualnego do komponentu kodowego

Przejście z Figma do kodu można potraktować jako sekwencję dość powtarzalnych kroków. Dla każdego komponentu:

1. Identyfikacja struktury – określenie, jakie będą tagi HTML (np. <button>, <span>, <svg>), jak wyglądają zagnieżdżenia.
2. Mapowanie styli na tokeny – powiązanie koloru tła, tekstu, spacingów, radiusów z istniejącymi tokenami.
3. Zdefiniowanie API komponentu – jakie propsy (React/Vue) czy klasy (HTML+CSS) odpowiadają wariantom z Figma.
4. Implementacja stanów – hover, focus, active, disabled, error.
5. Test z realną treścią – sprawdzenie zachowania dla dłuższych labeli, różnych języków, ikon.

W małym zespole sensowne jest, aby choć pierwszy komponent (najczęściej Button) przejść wspólnie – projektant i deweloper „przekodowują” go razem, uzgadniając zasady na przyszłość.

Przykład: przycisk w czystym HTML/CSS z tokenami

Załóżmy, że w Figma mamy komponent Button z wariantami primary i secondary, rozmiarami md i lg, oraz stanem disabled. W CSS może to wyglądać następująco:

.btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: var(--spacing-4);
  padding: var(--spacing-8) var(--spacing-16);
  border-radius: var(--radius-sm);
  font-size: var(--font-size-body);
  font-weight: 600;
  border: 1px solid transparent;
  cursor: pointer;
}

.btn--primary {
  background-color: var(--color-button-primary-bg);
  color: var(--color-button-primary-text);
}

.btn--secondary {
  background-color: transparent;
  color: var(--color-primary);
  border-color: var(--color-primary);
}

.btn--md {
  height: 40px;
}

.btn--lg {
  height: 48px;
}

.btn:disabled,
.btn--disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

HTML odzwierciedla z kolei strukturę komponentu z Figma, np. z opcjonalną ikoną po lewej:

<button class="btn btn--primary btn--md">
  <span class="btn__icon">...svg...</span>
  <span class="btn__label">Zapisz zmiany</span>
</button>

Jeżeli Figma pokazuje dokładnie taką strukturę (kontener + ikona + label), implementacja jest prostym odwzorowaniem zamiast interpretowania „co autor miał na myśli”.

Implementacja komponentu w React z wykorzystaniem tokenów

Przy pracy w React (analogicznie w Vue) komponenty z Figma dobrze jest od razu wiązać z tokenami, a nie z „surowymi” wartościami CSS. To ogranicza liczbę miejsc, w których trzeba będzie zmieniać kod przy korekcie design systemu.

Przykładowa implementacja komponentu Button może wyglądać tak:

type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'link';
type ButtonSize = 'sm' | 'md' | 'lg';

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant;
  size?: ButtonSize;
  icon?: 'left' | 'right' | 'none';
  isLoading?: boolean;
}

export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  icon = 'none',
  isLoading = false,
  children,
  ...rest
}) => {
  const classes = [
    'btn',
    `btn--${variant}`,
    `btn--${size}`,
    isLoading && 'btn--loading',
    icon !== 'none' && `btn--icon-${icon}`,
  ]
    .filter(Boolean)
    .join(' ');

  return (
    <button className={classes} disabled={rest.disabled || isLoading} {...rest}>
      {icon === 'left' && <span className="btn__icon btn__icon--left">{/* svg */}</span>}
      <span className="btn__label">{children}</span>
      {icon === 'right' && <span className="btn__icon btn__icon--right">{/* svg */}</span>}
    </button>
  );
};

Warianty z Figma odpowiadają bezpośrednio typom ButtonVariant i ButtonSize, a nazwy klas pokrywają się z tym, co jest używane w stylach bazujących na tokenach. Jeżeli panel wariantów w Figma zawiera dokładnie takie same nazwy, komunikacja między projektantem a deweloperem sprowadza się często do przesłania zrzutu ekranu z parametrami komponentu.

Vue i podejście z klasami pomocniczymi

W Vue część zespołów preferuje wzorzec z obliczanymi klasami zamiast rozbudowanego systemu propsów. Struktura myślenia pozostaje jednak zbliżona: warianty z Figma stają się kombinacjami klas.

<template>
  <button
    :class="buttonClasses"
    :disabled="disabled || isLoading"
    v-bind="$attrs"
  >
    <span v-if="icon === 'left'" class="btn__icon btn__icon--left">
      <slot name="icon-left" />
    </span>
    <span class="btn__label">
      <slot />
    </span>
    <span v-if="icon === 'right'" class="btn__icon btn__icon--right">
      <slot name="icon-right" />
    </span>
  </button>
</template>

<script setup lang="ts">
import { computed } from 'vue';

type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'link';
type ButtonSize = 'sm' | 'md' | 'lg';

const props = defineProps<{
  variant?: ButtonVariant;
  size?: ButtonSize;
  icon?: 'left' | 'right' | 'none';
  disabled?: boolean;
  isLoading?: boolean;
}>();

const buttonClasses = computed(() => [
  'btn',
  `btn--${props.variant ?? 'primary'}`,
  `btn--${props.size ?? 'md'}`,
  props.isLoading && 'btn--loading',
  props.icon && props.icon !== 'none' && `btn--icon-${props.icon}`,
].filter(Boolean));
</script>

Jeżeli komponent w Figma przewiduje slot na ikonę, w implementacji pojawiają się nazwane sloty icon-left i icon-right. Projektant dostaje wówczas do dyspozycji czytelne „miejsce” na ikonę, a deweloper prostą strukturę szablonu.

Łączenie komponentów z bibliotekami utility CSS (Tailwind, UnoCSS)

W małym zespole często korzysta się z Tailwinda lub podobnej biblioteki utility CSS, aby przyspieszyć implementację. Taki wybór nie wyklucza design systemu – przeciwnie, dobrze skonfigurowany Tailwind może być bezpośrednim odwzorowaniem tokenów uzgodnionych w Figma.

Przy stosowaniu utility CSS kluczowe bywa:

• przeniesienie tokenów do konfiguracji (np. tailwind.config.js – kolory, spacingi, font-size),
• utrzymywanie spójnych klas komponentowych (np. btn, card) nadbudowanych nad utility,
• unikanie „tworzenia designu w kodzie” poprzez dowolne łączenie klas nieodzwierciedlone w Figma.

Przykładowa definicja przycisku w Tailwind, nadal oparta na wcześniej uzgodnionych tokenach:

// tailwind.config.js (fragment)
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'var(--color-primary)',
        'button-primary-bg': 'var(--color-button-primary-bg)',
        'button-primary-text': 'var(--color-button-primary-text)',
      },
      spacing: {
        2: 'var(--spacing-4)',
        3: 'var(--spacing-8)',
        4: 'var(--spacing-16)',
      },
      borderRadius: {
        sm: 'var(--radius-sm)',
      },
    },
  },
};

// przykład komponentu Button z klasą bazową
const base =
  'inline-flex items-center justify-center gap-2 rounded-sm font-semibold border transition-colors';

const variants = {
  primary: 'bg-button-primary-bg text-button-primary-text border-transparent',
  secondary: 'bg-transparent text-primary border-primary',
};

const sizes = {
  md: 'h-10 px-4',
  lg: 'h-12 px-6',
};

Dzięki temu konfiguracja Tailwinda staje się niejako „implementacją” warstwy tokenów. Zmiana wartości w jednym miejscu modyfikuje jednocześnie Figma (po eksporcie) i stylowanie w kodzie.

Integracja z CSS-in-JS i bibliotekami typu styled-components / Emotion

Jeżeli projekt korzysta z CSS-in-JS, naturalnym rozwiązaniem bywa przeniesienie tokenów do obiektu theme. Wtedy komponenty mogą z nich korzystać bezpośrednio, a design system pozostaje spójny.

// theme.ts
export const theme = {
  colors: {
    buttonPrimaryBg: 'var(--color-button-primary-bg)',
    buttonPrimaryText: 'var(--color-button-primary-text)',
    primary: 'var(--color-primary)',
  },
  spacing: {
    xs: 'var(--spacing-4)',
    sm: 'var(--spacing-8)',
    md: 'var(--spacing-16)',
  },
  radius: {
    sm: 'var(--radius-sm)',
  },
};

// Button.tsx
import styled from '@emotion/styled';
import { theme } from './theme';

type Variant = 'primary' | 'secondary';

interface StyledProps {
  variant: Variant;
  size: 'md' | 'lg';
}

const StyledButton = styled.button<StyledProps>`
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: ${theme.spacing.xs};
  padding: ${theme.spacing.sm} ${theme.spacing.md};
  border-radius: ${theme.radius.sm};
  font-weight: 600;
  border: 1px solid transparent;
  cursor: pointer;

  ${({ variant }) =>
    variant === 'primary'
      ? `
      background-color: ${theme.colors.buttonPrimaryBg};
      color: ${theme.colors.buttonPrimaryText};
    `
      : `
      background-color: transparent;
      color: ${theme.colors.primary};
      border-color: ${theme.colors.primary};
    `}

  ${({ size }) =>
    size === 'md'
      ? `
      height: 40px;
    `
      : `
      height: 48px;
    `}

  &:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }
`;

Tokeny nadal pozostają „źródłem prawdy”, niezależnie od tego, czy są używane w CSS, Tailwindzie, czy w CSS-in-JS. Zmiana w theme przechodzi przez cały system komponentów.

Zachowanie spójności między Figma a kodem podczas zmian

Największym wyzwaniem nie jest zwykle pierwsze wdrożenie design systemu, lecz utrzymanie zgodności, gdy produkt ewoluuje. Przy małym zespole formalne procesy bywają przesadą, ale kilka prostych zasad bardzo pomaga.

Po pierwsze, każda zmiana w komponentach bazowych w Figma (Button, Input, Card) powinna mieć swój odpowiednik w zadaniu deweloperskim. W opisie zadania warto doprecyzować:

• które warianty komponentu są zmieniane (np. tylko primary i ghost),
• czy modyfikacja dotyczy tokenu (np. koloru) czy struktury (np. dodanie ikon),
• jakie ekrany w produkcie są potencjalnie dotknięte zmianą.

Po drugie, dobrze działa powiązanie merge requestu z komentarzem w Figma przy konkretnym komponencie. Projektant może wtedy łatwo prześledzić, czy implementacja odzwierciedla założenia, a deweloper ma jasne odniesienie wizualne.

Obsługa regresji wizualnych prostymi narzędziami

Visual regression testing kojarzy się z dużymi organizacjami, ale nawet w małym zespole można zastosować jego uproszczoną wersję. Dwa sprawdzone sposoby to:

• utrzymanie prostego „storybooka” lub strony z katalogiem komponentów, do której każdy może wejść i „rzucić okiem” po zmianach,
• okresowe zrzuty ekranu kluczowych widoków przed i po wdrożeniu istotnych korekt designu (nawet ręczne, w małych projektach często wystarczy).

Jeżeli system komponentów jest sensownie zbudowany, regresje ujawnią się często na stronie z katalogiem, zanim trafią na realne widoki. Taki katalog w praktyce zastępuje część automatycznych testów wizualnych przy znacznie mniejszym nakładzie pracy.

Mapowanie wyjątków: kiedy projekt wykracza poza istniejący system

Nawet najlepiej zaprojektowany system nie obejmie wszystkich możliwych przypadków. W którymś momencie pojawi się widok lub komponent, który z niczym nie chce się „poskładać”. Wtedy kluczowa jest decyzja: czy rozszerzamy system, czy świadomie tworzymy wyjątek.

Rozsądne kryteria przy podejmowaniu takiej decyzji to m.in.:

• czy nowy wzorzec pojawi się jednorazowo, czy raczej będzie wykorzystywany w wielu miejscach,
• czy można go zbudować jako kombinację istniejących komponentów (np. Card + Badge + Button) zamiast wprowadzać całkiem nowy byt,
• czy jego wprowadzenie wymaga nowych tokenów (kolory, spacingi) czy tylko innego ułożenia istniejących.

Jeśli wniosek jest taki, że to jednorazowy eksperyment, bywa rozsądnie oznaczyć go w kodzie i w Figma jako „experiment” albo „local pattern” i nie wikłać od razu całego systemu. Jeżeli natomiast widok staje się powtarzalny (np. nowy rodzaj karty produktu), wówczas zasadniejsze jest dodanie go do biblioteki komponentów i opisanie zasad użycia.

Rola prostego Storybooka lub „katalogu UI”

Nawet bez pełnego Storybooka mały zespół może utrzymywać prostą stronę z komponentami. Najważniejsze, aby:

• każdy komponent bazowy miał swoich kilka wariantów pokazanych w kontekście (różne stany, długości tekstu),
• adres tej strony był znany całemu zespołowi i regularnie wykorzystywany przy code review i przeglądach designu,
• katalog był aktualizowany równolegle ze zmianami w Figma.

Taki katalog pełni funkcję mostu: kiedy projektant tworzy nowy ekran, może na niego spojrzeć i sprawdzić, z jakich „klocków” realnie dysponuje zespół. Z kolei deweloperom ułatwia ocenę, czy nowy komponent to rzeczywiście coś nowego, czy tylko odmiana istniejącego wzorca.

Uzgadnianie nazewnictwa: Figma, kod, pliki

Chaos nazewniczy potrafi skutecznie unieważnić wysiłek włożony w system. Nawet przy dwóch, trzech osobach w zespole dobrze jest usiąść na godzinę i przejść przez podstawowe kategorie nazw:

• nazwy komponentów (Button vs Btn, TextField vs Input),
• nazwy wariantów (primary/secondary/ghost vs solid/outline/text),
• nazwy tokenów (color-primary vs brand-primary, spacing-8 vs space-md).

Jeżeli w Figma komponent nazywa się Primary Button, a w kodzie funkcjonuje jako MainAction, po kilku sprintach nikt już nie będzie pewien, czy rozmawiacie o tym samym elemencie. Spójny słownik pojęć jest w praktyce równie ważny jak same wartości tokenów.

Minimalne „procesy” w małym zespole, które realnie pomagają

Nie ma potrzeby tworzenia rozbudowanych procedur. Kilka prostych zasad często wystarcza, aby design system nie rozszedł się z kodem:

• zmiany w komponentach bazowych w Figma zawsze mają ticket i odniesienie w PR,
• przynajmniej jeden ekran „guides” w Figma jest aktualizowany przy większych zmianach wyglądu,
• raz na kilka sprintów krótki przegląd: porównanie kilku kluczowych widoków w produkcie z ich odpowiednikami w Figma,
• w opisie zadań projektowych doprecyzowanie: „nowy komponent do systemu” vs „jednorazowy wyjątek dla tej funkcji”.

W praktyce bywa różnie, ale trzymanie się takich prostych reguł sprawia, że system projektowy nie staje się martwym dokumentem, tylko realnym narzędziem pracy.

Praca iteracyjna: jak rozwijać system bez paraliżu

Design system w małym zespole nie powstaje „raz na zawsze”. Zwykle jest rozwijany małymi krokami przy okazji kolejnych funkcji. Dobrze sprawdza się podejście, w którym przy każdym większym zadaniu zespół zadaje sobie kilka pytań:

• czy można zrealizować tę funkcję wyłącznie istniejącymi komponentami,
• jeśli nie – czego konkretnie brakuje w obecnym systemie (nowy variant, size, czy zupełnie nowy komponent),

Najczęściej zadawane pytania (FAQ)

Co to jest design system w małym zespole i po co mi on, jeśli mam już ładne makiety w Figma?

Design system w małym zespole to nie tylko estetyczny plik w Figma, ale zestaw jasno opisanych reguł i komponentów, które da się konsekwentnie odtworzyć w HTML, CSS i kodzie komponentów. Chodzi o to, aby przy każdym nowym ekranie nie wymyślać od nowa fontów, kolorów czy odstępów, tylko korzystać z jednego źródła prawdy.

W praktyce oznacza to, że projektant i deweloper mają te same odpowiedzi na proste pytania: jak wygląda podstawowy przycisk, jaki kolor ma błąd formularza, jaki jest styl nagłówka H2. Ładny plik w Figma bez przełożenia na kod kończy się „interpretowaniem” designu przy każdym wdrożeniu i narastającym chaosem w interfejsie.

Jak przenieść komponenty z Figma do kodu (HTML/CSS/React) w małym zespole?

Bezpiecznym podejściem jest równoległe budowanie bibliotek: komponentów w Figma i komponentów w kodzie. Dla każdego elementu UI (np. Button, Input, Card) warto mieć:

• komponent Figma z określonymi stylami i wariantami,
• odpowiednik w kodzie (np. komponent React) korzystający z tych samych tokenów kolorów, typografii i spacingu.

W praktyce dobrze działa prosty workflow: projektant utrzymuje komponent w Figma, deweloper tworzy jego odpowiednik w kodzie i wspólnie uzupełniają krótką dokumentację „jak używać” (np. w Storybooku lub w pliku README). Każda zmiana w Figma powinna mieć odnotowany wpływ na kod – inaczej biblioteki szybko się rozjadą.

Jakie elementy powinien zawierać minimalny design system dla małego zespołu?

Co do zasady wystarczy zestaw fundamentów, które faktycznie będą używane w najbliższych miesiącach. Najczęściej jest to:

• system siatki i breakpointów (desktop / tablet / mobile),
• podstawowe style typograficzne: kilka poziomów nagłówków, tekst główny, opisy, etykiety,
• paleta kolorów z jasno nazwanymi rolami (primary, success, error itd.),
• kilka kluczowych komponentów: Button, Input, Select, Checkbox, Radio, Card, Modal, Navbar,
• prosty zestaw design tokens: kolory, font-size, line-height, spacing, border-radius.

Na starcie można pominąć rozbudowane wzorce (np. zaawansowane tabele, nietypowe layouty) i skupić się na spójności podstaw. Jeśli te elementy są stabilne, dokładanie kolejnych komponentów jest znacznie prostsze i mniej ryzykowne.

Jak sprawdzić, czy moje pliki w Figma nadają się na bazę design systemu?

Pierwszy krok to prosty audyt spójności. Chodzi o odpowiedź na pytanie, czy obecne makiety da się uogólnić do zestawu reguł, czy raczej każdy ekran jest projektowany „od zera”. Dobrym podejściem jest przejście po kilku kluczowych plikach i sprawdzenie:

• czy grid i marginesy są podobne między widokami,
• czy typografia korzysta ze wspólnych styli, czy z lokalnych ustawień,
• ile realnie występuje odcieni kolorów (np. ile różnych niebieskich),
• czy przyciski, pola formularzy, karty są komponentami Figma, czy „kopiuj-wklej” z drobnymi różnicami.

Jeżeli różnice są drobne i powtarzalne, zwykle wystarczy konsolidacja styli i komponentów. Jeśli każdy ekran jest inny, sensowniej jest najpierw uprościć i ujednolicić makiety, a dopiero potem próbować budować z nich system możliwy do odwzorowania w kodzie.

Jak wybrać, które komponenty wejściowo trafią do design systemu?

Dobrym filtrem są elementy, które najczęściej pojawiają się w produkcie i sprawiają najwięcej problemów przy wdrożeniu. W praktyce będą to zwykle:

• przyciski we wszystkich stanach (hover, active, disabled, focus),
• pola formularzy: input, textarea, select, checkbox, radio,
• podstawowe komponenty nawigacyjne: navbar, sidebar, zakładki,
• karty, listy elementów, proste tabele,
• modale, dialogi potwierdzeń, alerty/toasty.

Można przejść kilkanaście kluczowych ekranów i zliczyć, co realnie się powtarza. Często okazuje się, że „kilka różnych kart” to w istocie jeden komponent z różnymi wariantami (z obrazkiem/bez, z przyciskiem/bez). Taka obserwacja bardzo ułatwia projektowanie wariantów w Figma i w kodzie.

Jak rozwijać design system, gdy mamy mały zespół i mało czasu?

W małym zespole bardziej realne jest podejście inkrementalne niż jednorazowy „wielki refactor”. Oznacza to kilka prostych zasad:

• system rozwija się razem z produktem – każdy nowy feature korzysta już z nowych komponentów,
• stare widoki mogą przez jakiś czas współistnieć, ale nie są dalej rozwijane na „starych” stylach,
• raz na jakiś czas projektanci i deweloperzy robią krótką rewizję: co działa, co jest martwe tylko w Figma.

W praktyce bywa tak, że dopiero po kilku sprintach widać namacalne efekty spójności. Kluczowe jest ustalenie jasnego kontraktu w zespole: które komponenty są „oficjalne”, kto może je zmieniać i jak te zmiany są komunikowane reszcie.

Jak dokumentować design system, żeby nie ugrzęznąć w formalnościach?

W małym zespole wystarczy lekka, ale konkretna dokumentacja. Często sprawdza się jedna strona w Notion, Confluence albo plik markdown w repozytorium, gdzie opisane są:

• podstawowe zasady (siatka, typografia, kolory, breakpoints),
• lista dostępnych komponentów z linkiem do Figma i do implementacji w kodzie,
• zwięzłe wytyczne „kiedy używać” danego komponentu i jakie ma stany.

Taka dokumentacja nie musi być rozbudowana, ale powinna być aktualna. W praktyce problemem nie jest zwykle brak informacji, tylko rozjazd między tym, co jest w Figma, a tym, co trafiło do kodu. Krótkie notatki przy każdej zmianie komponentu ograniczają liczbę nieporozumień między projektantem a deweloperem.