Kurs JavaScript i React · Moduł 15: Wzorce i architektura
Atomic Design w React - Budowanie stacji z atomów
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:
- Atomy: najmniejsze części, których nie ma sensu dzielić dalej, jak śruba, lampka czy przełącznik. W React to
Button,Input,BadgeczyProgressBar. - Molekuły: kilka atomów, które razem pełnią jedną funkcję, jak przełącznik z lampką i podpisem. Na przykład
SearchBartoInputiButton. - Organizmy: samodzielne sekcje interfejsu złożone z molekuł i atomów, jak cały panel systemów na mostku.
- Szablony (templates): układ strony ze slotami, ale bez prawdziwych danych, jak plan pokładu, na którym zaznaczono, gdzie stanie który panel.
- 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:
- Zidentyfikuj powtarzające się elementy UI: te same przyciski, paski i plakietki w wielu miejscach.
- Wyodrębnij z nich atomy, na przykład
Button,InputiBadge. - Połącz atomy w molekuły, takie jak
SearchBar,UserCardczyStatusRow. - Zbuduj z molekuł organizmy, takie jak
CrewPaneliSystemsPanel. - 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. Na którym poziomie Atomic Design znajduje się komponent SearchBar łączący Input i Button?
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: