Projekt 5: mini system komponentów CSS

Cel projektu

Celem jest stworzenie mini biblioteki komponentów, którą można wykorzystać w małej aplikacji edukacyjnej albo portfolio. System ma być prosty, ale spójny i przewidywalny.

• Tokeny definiują kolory, odstępy, promienie, cienie i fokus.
• Komponenty mają bazę oraz warianty zamiast osobnych klas jednorazowych.
• Stany hover, focus-visible, active, disabled, error i success są spójne.
• Komponenty działają w układzie mobile-first.
• Demo pokazuje realne użycie systemu, nie tylko pojedyncze elementy bez kontekstu.

Brief projektu

Zaprojektuj mini system komponentów dla „CSS Academy UI Kit”. System ma wystarczyć do zbudowania małej sekcji aplikacji: przyciski, karta kursu, alert statusu i pole formularza.

Kryteria sukcesu

Mini system komponentów jest dobry wtedy, gdy kilka różnych elementów wygląda jak część jednego produktu i da się je rozwijać bez walki ze specyficznością.

• Tokeny semantyczne są nazwane rolą, nie kolorem technicznym.
• Każdy komponent ma bazową klasę i ograniczony zestaw wariantów.
• Selektory nie są głębsze niż wymaga tego komponent.
• Warianty nie nadpisują przypadkowo stylów innych komponentów.
• Stany interakcji są dostępne klawiaturą.
• Kod można skopiować do innej strony bez przepisywania fundamentów.

Zakres systemu

Dobry mini system nie próbuje rozwiązać wszystkich problemów naraz. W tym projekcie zakres jest świadomie mały.

• Tokens: kolory, powierzchnie, border, fokus, odstępy, promienie i cień.
• Button: wariant primary, secondary, ghost i disabled.
• Card: karta bazowa oraz karta wyróżniona.
• Alert: success, warning i error.
• Field: label, input, help text, error i success.

Struktura HTML

Komponenty powinny mieć czytelną strukturę i semantykę. System klas nie zastępuje poprawnego HTML.

Kopiuj<article class="ui-card ui-card--featured">
  <p class="ui-card__meta">Moduł CSS</p>
  <h3>Responsive Layout</h3>
  <p>Ćwiczenia z Grid, Flexbox i breakpointów.</p>
  <a class="ui-button ui-button--primary" href="#">Otwórz moduł</a>
</article>

Klasy opisują rolę komponentu, a HTML nadal odpowiada za strukturę treści.

Tokeny systemu

Tokeny to kontrakt między komponentami. Jeśli każdy komponent używa tych samych ról, cały interfejs zachowuje spójność.

Kopiuj.ui-system {
  --ui-bg: #f8fafc;
  --ui-surface: #ffffff;
  --ui-text: #0f172a;
  --ui-muted: #64748b;
  --ui-border: #dbe3ef;
  --ui-accent: #2563eb;
  --ui-success: #16a34a;
  --ui-warning: #d97706;
  --ui-error: #dc2626;
  --ui-radius: 12px;
}

Nie twórz tokenu dla każdej pojedynczej wartości. Token ma mieć sens jako decyzja systemowa.

Przyciski

Przycisk jest komponentem z największą liczbą stanów. Zacznij od bazy, potem dodaj warianty i stany.

Kopiuj.ui-button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  min-height: 2.75rem;
  border-radius: 999px;
  font-weight: 800;
  text-decoration: none;
}

.ui-button--primary {
  background: var(--ui-accent);
  color: #ffffff;
}

Wariant nie powinien powtarzać całej definicji przycisku. Wariant zmienia tylko to, co naprawdę różni dany przypadek.

Karty

Karta jest powierzchnią dla treści. System powinien określać jej padding, border, radius i rytm wewnętrzny.

Kopiuj.ui-card {
  display: grid;
  gap: .75rem;
  padding: 1rem;
  border: 1px solid var(--ui-border);
  border-radius: var(--ui-radius);
  background: var(--ui-surface);
}

.ui-card--featured {
  border-color: #93c5fd;
}

Karta nie powinna wiedzieć, w jakim layoucie się znajdzie. Layout należy do rodzica, komponent do własnej zawartości.

Alerty

Alerty komunikują status. Nie opieraj ich wyłącznie na kolorze; dodaj tytuł, tekst i jasną rolę wizualną.

Kopiuj.ui-alert {
  padding: .85rem 1rem;
  border: 1px solid var(--ui-border);
  border-radius: var(--ui-radius);
  background: var(--ui-surface);
}

.ui-alert--success {
  border-color: #bbf7d0;
  background: #f0fdf4;
}

Jeśli alert oznacza błąd krytyczny, powinien być blisko miejsca działania albo widoczny w podsumowaniu formularza.

Pola formularza

Pole formularza składa się z labelki, kontrolki, tekstu pomocniczego i opcjonalnego błędu. To naturalny kandydat na komponent.

Kopiuj.ui-field {
  display: grid;
  gap: .4rem;
}

.ui-field input {
  min-height: 2.75rem;
  border: 1px solid var(--ui-border);
  border-radius: var(--ui-radius);
  font: inherit;
}

Komponent pola powinien wspierać stany error i success bez zmiany struktury HTML.

Stany i warianty

Stany pokazują chwilowe zachowanie komponentu, a warianty opisują trwałą odmianę. Nie mieszaj tych dwóch pojęć.

Kopiuj.ui-button:hover {
  transform: translateY(-1px);
}

.ui-button:focus-visible {
  outline: 3px solid #bfdbfe;
  outline-offset: 3px;
}

.ui-button:disabled {
  cursor: not-allowed;
  opacity: .58;
}

Stan disabled nie jest wariantem wizualnym. To stan funkcjonalny, który musi komunikować brak dostępności.

Responsywność

System komponentów powinien działać w różnych kontenerach. Karta, alert i pole formularza nie mogą zakładać stałej szerokości strony.

Kopiuj.ui-system__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 14rem), 1fr));
  gap: 1rem;
}

Responsywność mini systemu polega na tym, że komponenty nie rozpychają rodzica i dobrze znoszą krótszy oraz dłuższy tekst.

Demo systemu

Poniżej znajduje się gotowy mini system komponentów: tokeny, przyciski, karty, alerty i pole formularza użyte w jednym małym widoku aplikacji.

Najczęstsze błędy początkujących

• Budowanie „systemu” z jednorazowych klas, które działają tylko w jednym widoku.
• Nazywanie tokenów technicznie, na przykład --blue, zamiast semantycznie, na przykład --color-accent.
• Tworzenie zbyt wielu wariantów zanim powstanie realna potrzeba.
• Powtarzanie pełnej definicji komponentu w każdym wariancie.
• Brak spójnych stanów focus-visible i disabled.
• Projektowanie komponentów, które zakładają stałą szerokość rodzica.

Zadanie projektowe

Zbuduj własny mini system komponentów CSS dla małej aplikacji, portfolio albo strony kursu.

• Zdefiniuj tokeny dla tła, powierzchni, tekstu, obramowania, akcentu, sukcesu, ostrzeżenia, błędu, fokusu i promienia.
• Utwórz komponent przycisku z wariantami primary, secondary, ghost i disabled.
• Utwórz komponent karty z wariantem wyróżnionym.
• Utwórz komponent alertu z wariantami success, warning i error.
• Utwórz komponent pola formularza z labelką, help text i stanem błędu.
• Dodaj widoczne stany hover, active i focus-visible.
• Sprawdź system w układzie jednej kolumny i responsywnej siatki.
• Udokumentuj krótko, kiedy używać każdego wariantu.

Checklista jakości

• Tokeny są semantyczne i używane przez komponenty.
• Komponenty mają bazę i ograniczoną liczbę wariantów.
• Stany focus-visible są widoczne na przyciskach i polach.
• Disabled wygląda i zachowuje się jak stan nieaktywny.
• Alerty mają tekst, nie tylko kolor.
• Karty nie zależą od konkretnego layoutu strony.
• Na 390px nie ma poziomego overflow.
• System da się wykorzystać w drugim widoku bez zmiany nazw klas.

Podsumowanie roadmapy

Mini system komponentów domyka całą ścieżkę CSS Academy. Po przejściu roadmapy masz fundamenty CSS, layout, responsywność, komponenty UI, formularze, dane, efekty, organizację arkusza, nowoczesne funkcje CSS i pięć praktycznych projektów portfolio.

Najlepszy następny krok to utrzymanie jakości: przegląd wspólnej nawigacji, wydzielenie listy lekcji jako źródła prawdy i ewentualne uporządkowanie CSS w sekcje lub pliki.