Kurs JavaScript i React · Moduł 15: Wzorce i architektura

Atomic Design w React - Budowanie stacji z atomów

7 min czytania ·
W tej lekcji8

Stacja orbitalna rozrosła się do dwudziestu ekranów. Na każdym jest przycisk, pasek postępu i plakietka statusu, ale każdy zespół napisał je po swojemu: tu pasek ma sześć pikseli wysokości, tam osiem, a czerwony alarm ma trzy różne odcienie. Gdy Komandor Nova prosi, żeby wszystkie plakietki krytyczne wyglądały tak samo, szukasz ich w czterdziestu plikach. Problemem nie jest żaden pojedynczy komponent, tylko brak planu, który mówi, z jakich części składa się interfejs. Taki plan daje Atomic Design.

Pięć poziomów Atomic Design

Atomic Design to sposób myślenia o interfejsie, który Brad Frost opisał w 2013 roku, a potem rozwinął w książce "Atomic Design". Nazwy zapożycza z przyrody: atomy łączą się w molekuły, a molekuły w organizmy. Na stacji wygląda to tak:

  1. Atomy: najmniejsze części, których nie ma sensu dzielić dalej, jak śruba, lampka czy przełącznik. W React to Button, Input, Badge czy ProgressBar.
  2. Molekuły: kilka atomów, które razem pełnią jedną funkcję, jak przełącznik z lampką i podpisem. Na przykład SearchBar to Input i Button.
  3. Organizmy: samodzielne sekcje interfejsu złożone z molekuł i atomów, jak cały panel systemów na mostku.
  4. Szablony (templates): układ strony ze slotami, ale bez prawdziwych danych, jak plan pokładu, na którym zaznaczono, gdzie stanie który panel.
  5. Strony (pages): szablon wypełniony prawdziwymi danymi, czyli pokład w dniu misji.

Kolejność poziomów jest zawsze ta sama, od najmniejszego do największego: atomy, molekuły, organizmy, szablony, strony. Frost podkreśla jednak, że to model, a nie proces krok po kroku: nad kilkoma poziomami możesz pracować jednocześnie.

Atomy - najmniejsze części

Atom nie wie, gdzie zostanie użyty. Dostaje dane przez propsy i zawsze wygląda tak samo. Najprostszy jest Badge, czyli kolorowa plakietka z krótkim tekstem:

// atoms/Badge.jsx
function Badge({ children, color = 'blue' }) {
  return <span className={`badge badge-${color}`}>{children}</span>;
}

Kolor przychodzi z zewnątrz jako nazwa wariantu, a nie jako kod koloru, więc sam odcień ustalasz w jednym miejscu: w stylach klasy badge-red. Gdy alarm ma zmienić odcień, poprawiasz jedną linię CSS, a nie czterdzieści plików.

Ciekawszy jest ProgressBar. Wizualnie to dwa prostokąty, ale czytnik ekranu musi wiedzieć, że to pasek postępu, czego dotyczy i jaką ma wartość. Dlatego pasek dostaje rolę progressbar, opis w aria-label i trzy atrybuty z liczbami:

// atoms/ProgressBar.jsx
function ProgressBar({ value, label }) {
  return (
    <div
      className="progress"
      role="progressbar"
      aria-label={label}
      aria-valuenow={value}
      aria-valuemin={0}
      aria-valuemax={100}
    >
      <div className="progress-fill" style={{ width: `${value}%` }} />
    </div>
  );
}

aria-valuenow podaje bieżącą wartość, a aria-valuemin i aria-valuemax jej zakres. Szerokość wypełnienia to ta sama liczba zapisana w procentach, więc wygląd i opis dla czytnika nigdy się nie rozjadą. Przeglądarka ma też gotowy element <progress>. Własny pasek z rolą progressbar budujemy wtedy, gdy potrzebujemy pełnej kontroli nad wyglądem, i wtedy sami musimy go opisać.

Molekuły - atomy z jednym zadaniem

Molekuła łączy kilka atomów w coś, co ma już znaczenie. Klasyczny przykład to wyszukiwarka: atom Input, czyli pole tekstowe w stylu stacji, i atom Button razem służą do jednego, do szukania:

// molecules/SearchBar.jsx
function SearchBar({ onSearch }) {
  const [query, setQuery] = useState('');

  return (
    <div className="search-bar">
      <Input value={query} onChange={(e) => setQuery(e.target.value)} />
      <Button onClick={() => onSearch(query)}>Szukaj</Button>
    </div>
  );
}

SearchBar pamięta wpisywany tekst, ale nie wie, czego szuka: zapytanie oddaje przez onSearch. Tak samo powstaje UserCard (avatar, imię i plakietka z rolą) albo wiersz statusu StatusRow, który za chwilę złoży się w większy panel:

// molecules/StatusRow.jsx
function StatusRow({ label, value, color }) {
  return (
    <div className="status-row">
      <span className="status-label">{label}</span>
      <ProgressBar value={value} label={label} />
      <Badge color={color}>{value}%</Badge>
    </div>
  );
}

StatusRow nie dodaje żadnego stylu poza układem: wygląd paska i plakietki należy do atomów. Gdy poprawisz ProgressBar, poprawi się w każdym wierszu na stacji.

Organizmy - całe sekcje interfejsu

Organizm to sekcja, którą można postawić na ekranie i od razu zrozumieć, do czego służy. Panel SystemsPanel dostaje listę systemów i dla każdego rysuje jeden StatusRow. Sam decyduje tylko o jednym: mapa statusColors mówi, jaki kolor plakietki odpowiada jakiemu statusowi:

// organisms/SystemsPanel.jsx
const statusColors = { ok: 'green', warning: 'orange', critical: 'red' };

function SystemsPanel({ systems }) {
  return (
    <section className="systems-panel">
      <h2>Systemy statku</h2>
      {systems.map(system => (
        <StatusRow
          key={system.id}
          label={system.name}
          value={system.level}
          color={statusColors[system.status]}
        />
      ))}
    </section>
  );
}

Mapa tłumaczy język danych (ok, warning, critical) na język atomów (green, orange, red). Atomy nie znają statusów systemów, a dane nie znają kolorów. Tak samo zbudujesz CrewPanel: SearchBar nad listą kart UserCard.

Szablony i strony

Szablon to układ bez treści. DashboardTemplate mówi tylko, gdzie stoi nagłówek, panel boczny i część główna, a zawartość dostaje przez sloty, jak układy z pierwszej lekcji modułu:

// templates/DashboardTemplate.jsx
function DashboardTemplate({ header, sidebar, main }) {
  return (
    <div className="dashboard">
      <header className="dash-header">{header}</header>
      <aside className="dash-sidebar">{sidebar}</aside>
      <main className="dash-main">{main}</main>
    </div>
  );
}

Strona MissionDashboard to ostatni poziom: bierze szablon i wkłada w niego organizmy z prawdziwymi danymi. Dane pobiera hook useFetch, w nagłówku stoi organizm NavigationBar, a dopóki dane się ładują, strona pokazuje Spinner:

// pages/MissionDashboard.jsx
function MissionDashboard() {
  const systems = useFetch('/api/systems');
  const crew = useFetch('/api/crew');

  if (systems.loading || crew.loading) return <Spinner />;

  return (
    <DashboardTemplate
      header={<NavigationBar />}
      sidebar={<CrewPanel crew={crew.data} />}
      main={<SystemsPanel systems={systems.data} />}
    />
  );
}

W tym układzie tylko strona wie, skąd pochodzą dane. W projekcie końcowym zobaczysz, że po hook z danymi może sięgnąć też organizm, ale nigdy atom ani molekuła. Ten sam szablon z innymi organizmami da ekran załogi, a ten sam SystemsPanel pokaże dane testowe w katalogu komponentów.

Struktura folderów

Poziomy Atomic Design najłatwiej zobaczyć w drzewie plików. Każdy poziom dostaje własny folder w src/components, a nazwa folderu od razu mówi, jak duży jest komponent w środku:

src/
  components/
    atoms/
      Button.jsx
      Input.jsx
      Badge.jsx
      ProgressBar.jsx
    molecules/
      SearchBar.jsx
      StatusRow.jsx
      UserCard.jsx
    organisms/
      SystemsPanel.jsx
      CrewPanel.jsx
      NavigationBar.jsx
    templates/
      DashboardTemplate.jsx
    pages/
      MissionDashboard.jsx

Ścieżka importu powtarza to drzewo. Każdy plik eksportuje swój komponent przez export default, więc przycisk importujesz z components/atoms/Button, a wiersz statusu z components/molecules/StatusRow:

import Button from 'components/atoms/Button';
import StatusRow from 'components/molecules/StatusRow';

Taka ścieżka jest liczona od folderu src, więc projekt musi o tym wiedzieć: w Vite dodajesz alias w resolve.alias, a w Next.js ustawiasz baseUrl albo paths w pliku jsconfig.json. Bez tego piszesz ścieżkę względną, na przykład ../atoms/Button.

Cena porządku

Atomic Design nie jest za darmo. Główny kompromis brzmi tak: zyskujesz większą reużywalność komponentów, ale płacisz większą liczbą plików i bardziej złożoną strukturą folderów. Mały formularz rozbity na pięć poziomów to kilkanaście plików zamiast jednego, a zespół musi się umówić, czy dany komponent to jeszcze molekuła, czy już organizm. W dużej aplikacji z dziesiątkami ekranów ta cena szybko się zwraca: przycisk poprawiasz w jednym miejscu, nowa osoba w zespole od razu wie, gdzie szukać wiersza statusu, a atomy testujesz w izolacji. W aplikacji z trzema widokami wystarczy prosty podział na components/ i pages/.

Refaktoryzacja monolitu krok po kroku

Rzadko zaczynasz od zera. Częściej dostajesz jeden ogromny komponent panelu i chcesz go uporządkować. Idź od dołu, w tej kolejności:

  1. Zidentyfikuj powtarzające się elementy UI: te same przyciski, paski i plakietki w wielu miejscach.
  2. Wyodrębnij z nich atomy, na przykład Button, Input i Badge.
  3. Połącz atomy w molekuły, takie jak SearchBar, UserCard czy StatusRow.
  4. Zbuduj z molekuł organizmy, takie jak CrewPanel i SystemsPanel.
  5. Na końcu stwórz szablon i stronę, które ułożą organizmy na ekranie.

Po każdym kroku aplikacja powinna wyglądać i działać tak samo jak przed nim. Jeśli coś się zmieniło, od razu wiesz, który krok to zepsuł.

Moja rada: nie zakładaj pięciu pustych folderów pierwszego dnia. Zacznij od atomów, które naprawdę się powtarzają, a kolejne poziomy dokładaj, gdy kod sam o nie poprosi. Gdy nie wiesz, gdzie odłożyć komponent, zapytaj, czy ma sens sam w sobie: atom działa wszędzie, molekuła potrzebuje atomów, a organizm to już cała sekcja ekranu. W następnej lekcji poznasz Provider Pattern i maszyny stanów, które przydadzą się, gdy organizmy zaczną dzielić wspólny stan.

Pamiętaj: stację składasz z małych, sprawdzonych części, a nie rzeźbisz każdego ekranu od nowa.

Kod do tej lekcji: App.jsx
import React, { useState } from 'react';

// ============ ATOMY ============

function Button({ variant = 'primary', children, ...props }) {
  return (
    <button className={`btn btn-${variant}`} {...props}>
      {children}
    </button>
  );
}

function Input(props) {
  return <input className="input" {...props} />;
}

function Badge({ children, color = 'blue' }) {
  return <span className={`badge badge-${color}`}>{children}</span>;
}

function ProgressBar({ value, label }) {
  return (
    <div
      className="progress"
      role="progressbar"
      aria-label={label}
      aria-valuenow={value}
      aria-valuemin={0}
      aria-valuemax={100}
    >
      <div className="progress-fill" style={{ width: `${value}%` }} />
    </div>
  );
}

function Avatar({ name }) {
  return <span className="avatar" aria-hidden="true">{name[0]}</span>;
}

// ============ MOLEKUŁY ============

function SearchBar({ onSearch, placeholder = 'Szukaj...' }) {
  const [query, setQuery] = useState('');
  return (
    <div className="search-bar">
      <Input
        placeholder={placeholder}
        aria-label={placeholder}
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <Button onClick={() => onSearch(query)}>Szukaj</Button>
    </div>
  );
}

function StatusRow({ label, value, color }) {
  return (
    <div className="status-row">
      <span className="status-label">{label}</span>
      <ProgressBar value={value} label={label} />
      <Badge color={color}>{value}%</Badge>
    </div>
  );
}

// Wartości ról zostają w kodzie po angielsku, załoga widzi polskie etykiety
const roleLabels = { captain: 'Kapitan', medic: 'Medyk', engineer: 'Inżynier', navigator: 'Nawigator' };

function UserCard({ user, onClick }) {
  return (
    <button className="user-card" onClick={onClick}>
      <Avatar name={user.name} />
      <span className="user-info">
        <span className="user-name">{user.name}</span>
        <Badge color={user.role === 'captain' ? 'gold' : 'blue'}>{roleLabels[user.role]}</Badge>
      </span>
    </button>
  );
}

// ============ ORGANIZMY ============

const statusColors = { ok: 'green', warning: 'orange', critical: 'red' };

function SystemsPanel({ systems }) {
  return (
    <section className="systems-panel">
      <h2>Systemy statku</h2>
      {systems.map(system => (
        <StatusRow
          key={system.id}
          label={system.name}
          value={system.level}
          color={statusColors[system.status]}
        />
      ))}
    </section>
  );
}

function CrewPanel({ crew, onSelect }) {
  const [query, setQuery] = useState('');
  // Lista wyliczana podczas renderowania, bez kopii propsów w stanie
  const visible = crew.filter(m => m.name.toLowerCase().includes(query.toLowerCase()));

  return (
    <section className="crew-panel">
      <h2>Załoga</h2>
      <SearchBar onSearch={setQuery} placeholder="Szukaj w załodze..." />
      {visible.map(member => (
        <UserCard key={member.id} user={member} onClick={() => onSelect(member)} />
      ))}
      {visible.length === 0 && <p className="empty">Brak wyników</p>}
    </section>
  );
}

// ============ SZABLON (TEMPLATE): sam układ, bez danych ============

function DashboardTemplate({ header, sidebar, main }) {
  return (
    <div className="dashboard">
      <header className="dash-header">{header}</header>
      <aside className="dash-sidebar">{sidebar}</aside>
      <main className="dash-main">{main}</main>
    </div>
  );
}

// ============ STRONA (PAGE): szablon wypełniony danymi ============

const crew = [
  { id: 1, name: 'Komandor Nova', role: 'captain' },
  { id: 2, name: 'Dr Stellar', role: 'medic' },
  { id: 3, name: 'Astro', role: 'engineer' },
  { id: 4, name: 'Ra', role: 'navigator' },
];

const systemNames = { engines: 'Silniki', shields: 'Osłony', lifeSupport: 'Podtrzymanie życia', comms: 'Łączność' };

const levelToStatus = (level) => (level >= 70 ? 'ok' : level >= 40 ? 'warning' : 'critical');

export default function App() {
  const [levels, setLevels] = useState({ engines: 95, shields: 42, lifeSupport: 100, comms: 18 });
  const [selected, setSelected] = useState(null);

  const systems = Object.keys(levels).map(id => ({
    id,
    name: systemNames[id],
    level: levels[id],
    status: levelToStatus(levels[id]),
  }));

  const boostShields = () =>
    setLevels(prev => ({ ...prev, shields: Math.min(prev.shields + 20, 100) }));

  return (
    <DashboardTemplate
      header={<h1>Atomic Design w React</h1>}
      sidebar={<CrewPanel crew={crew} onSelect={setSelected} />}
      main={
        <>
          <SystemsPanel systems={systems} />
          <Button variant="secondary" onClick={boostShields} disabled={levels.shields === 100}>
            Doładuj osłony o 20%
          </Button>
          {selected && (
            <div className="detail-box">
              <h3>Wybrano: {selected.name}</h3>
              <p>Rola: {roleLabels[selected.role]}</p>
            </div>
          )}
          <div className="hierarchy">
            <h2>Poziomy na tym ekranie</h2>
            <div className="level"><Badge color="blue">Atomy</Badge><span>Button, Input, Badge, ProgressBar, Avatar</span></div>
            <div className="level"><Badge color="green">Molekuły</Badge><span>SearchBar, StatusRow, UserCard</span></div>
            <div className="level"><Badge color="orange">Organizmy</Badge><span>SystemsPanel, CrewPanel</span></div>
            <div className="level"><Badge color="purple">Szablon</Badge><span>DashboardTemplate</span></div>
            <div className="level"><Badge color="gold">Strona</Badge><span>Ten komponent App</span></div>
          </div>
        </>
      }
    />
  );
}

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Na którym poziomie Atomic Design znajduje się komponent SearchBar łączący Input i Button?

  2. 2. Jaki jest główny kompromis stosowania Atomic Design w dużych projektach React?

Zadania praktyczne w grze

  • Edytor kodu

    Zbuduj panel systemów statku z atomów, molekuły i organizmu. Atom ProgressBar ogranicza wartość do zakresu 0-100 (stała percent): ___BLANK1___ to wartość atrybutu aria-valuenow, a ___BLANK2___ to szerokość wypełnienia w procentach jako napis, na przykład '45%'. Molekuła StatusRow łączy atomy: ___BLANK3___ to atom ProgressBar z wartością value i etykietą label (z niej czytnik ekranu bierze nazwę paska), wstawiony między nazwą a odznaką. Organizm SystemsPanel tworzy StatusRow dla każdego systemu: ___BLANK4___ to kolor odznaki odczytany z STATUS_COLORS według statusu systemu (online, degraded, offline).

  • Układanie w pionie

    Ułóż poziomy Atomic Design od najmniejszego do największego:

  • Klikanie w kolejności

    Kliknij elementy ścieżki importu atomu Button w prawidłowej kolejności:

  1. Zadanie z kodemPraktyka: Atomic Design
  2. PytaniePoziomy Atomic Design
  3. PytanieKompromisy Atomic Design
  4. Ułóż w kolejnościHierarchia Atomic Design
  5. Kliknij w kolejnościStruktura folderu Atomic Design

Przydatne artykuły