Design System — v 1.0

Założenia

Podstawy budowania interfejsów. Każda decyzja wynika z tych reguł. System składa się z etapów, brak konsekwentnego stosowania podstawowych założeń prowadzi do późniejszych utrudnień.

Sekcja I

Zasady UX/UI

Prawa psychologii poznawczej i ergonomii. Technologia to tylko narzędzie do ich egzekwowania.

Prostota i minimalizm

Najwyższym priorytetem jest używanie komponentów shadcn/ui oraz zasad prfct.dev. Spójność systemu jest ważniejsza niż unikalność pojedynczego widoku.

Funkcja Definiuje Formę

Unikamy elementów czysto dekoracyjnych. Cień oznacza oś Z i interaktywność. Obramowanie separuje konteksty. Każdy piksel ma zadanie.

Prawo Bliskości (Gestalt)

Pusta przestrzeń to główny budulec struktury. Elementy powiązane logicznie muszą być wizualnie bliżej siebie niż elementy niepowiązane.

Zasada Jednego Mrugnięcia

Użytkownik musi zawsze wiedzieć, gdzie jest i co jest główną akcją na ekranie. Jasna hierarchia nagłówków i jednoznaczne CTA realizują tę zasadę.

Prawo Fittsa (Mobile)

Wszystkie elementy klikalne muszą być łatwo dostępne pod ręką i odpowiednio duże. Główne akcje trzymamy w naturalnym zasięgu kciuka.

Ciągły Feedback

Każda akcja wymaga natychmiastowej reakcji wizualnej: stany hover, pierścienie focusu przy nawigacji klawiaturą, wskaźniki ładowania dla operacji asynchronicznych.

Sekcja II

Zasady Kodu

Sześć reguł gwarantujących spójność, dostępność i długoterminową utrzymywalność.

Jedno Źródło Prawdy (SSOT)

Zmiana tokenu w globals.css aktualizuje kaskadowo całą aplikację. Zakaz prefixu dark: — tryb ciemny obsługują wyłącznie tokeny.

Wszystko Mobile-First

Klasy bazowe definiują widok smartfona. Breakpointy md:, lg: służą wyłącznie do rozbudowy w górę — nigdy do łatania layoutu na małych ekranach.

Semantyka Ponad Wygląd

Nazywamy intencję (--destructive), nie cechę wizualną (--red). Tagi HTML służą logice i SEO, nie stylowaniu.

Bezwzględna Dostępność

Zakaz outline-none bez zastępczego focus-visible:ring. System musi być w pełni nawigowany klawiaturą. Kontrast 4.5:1 (WCAG AA).

Polimorfizm zamiast Duplikacji

Używamy asChild z Radix UI, aby linki mogły wyglądać jak przyciski bez zagnieżdżania tagów interaktywnych. Warianty obsługiwane wyłącznie przez CVA.

Czystość Ekosystemu

Wyłącznie lucide-react dla ikon (dziedziczące text-current). Obrazy wyłącznie przez <Image> z next/image — nigdy natywne <img>.

Sekcja III

Architektura i Layout

Paradygmat React Server Components i zmodyfikowany Atomic Design. Cztery warstwy z ograniczonymi, ściśle zdefiniowanymi odpowiedzialnościami.

Prymitywy

Czyste, proste atomy (Button, Input, Badge). Nic nie wiedzą o tym, gdzie się znajdują na stronie.

Szkielet

Oddzielenie układu (Grid, Stack, Section) od komponentów to gwarancja braku magicznych marginesów. Layout robi przestrzeń, UI robi wygląd.

Wzorce

Złożone, gotowe sekcje: HeroSection, PricingTable, LoginForm. Szablony do szybkiego budowania.

Widoki

Plik strony ma być kompozycją klocków z blocks wrzuconych w layout. Zero logiki i kilometrów kodu.