Przejdź do treści
StriveLab
Next.jsReact

Design System w Next.js od zera: Tailwind, CVA i Radix UI

Poznaj nowoczesną architekturę komponentów. Zobacz, jak połączyć Tailwind, Radix UI i CVA, aby stworzyć skalowalny system projektowy od zera.

Maciej Sala

Founder StriveLab

4 min czytaniaOpublikowano 10 kwietnia 2026 (Aktualizacja 17 lipca 2026)

Po co budować własny design system w Next.js?

Zyskujesz na tym potrójnie: spójny wygląd, szybsze pisanie i mniej dziwnych bugów CSS, które biorą się z ręcznego powielania klas. Zestaw Tailwind + CVA + Radix UI sprawdza się tu od lat — łączy utility-first CSS z typowanymi wariantami i mechanizmami dostępności dla interaktywnych komponentów.

Stack design systemu: Tailwind, CVA i Radix UI

  • Tailwind CSS — utility classes do stylowania
  • — typowane warianty komponentów
  • Radix UI — (bez stylów) komponenty z wbudowaną dostępnością (ARIA)
  • tailwind-merge — inteligentne łączenie klas Tailwind (rozwiązuje konflikty)
  • clsx — warunkowe klasy CSS

Instalacja CVA, Radix UI i pozostałych zależności

Code
npm install class-variance-authority clsx tailwind-merge radix-ui lucide-react

Radix nadal udostępnia osobne pakiety @radix-ui/react-*, ale pakiet radix-ui upraszcza zależności i pozwala importować prymitywy z jednego miejsca. Powyższe polecenie zakłada, że Tailwind CSS jest już skonfigurowany w projekcie Next.js.

Helper cn() jako fundament design systemu

Funkcja cn() łączy clsx (warunkowe klasy) z tailwind-merge (rozwiązywanie konfliktów):

Code
// lib/utils.ts
import { type ClassValue, clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'
 
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Dlaczego to ważne:

Code
// Bez tailwind-merge — konflikty klas
<div className="bg-red-500 bg-blue-500" /> // Która wygra? Nieprzewidywalne.
 
// Z cn() — ostatnia klasa wygrywa
<div className={cn('bg-red-500', 'bg-blue-500')} /> // bg-blue-500

Komponent Button z CVA i wariantami

CVA pozwala definiować warianty komponentu jako obiekt TypeScript — z pełnym autocompletem i type safety:

Code
// components/ui/button.tsx
import { cva, type VariantProps } from 'class-variance-authority'
import { Slot } from 'radix-ui'
import { forwardRef, type ButtonHTMLAttributes } from 'react'
import { cn } from '@/lib/utils'
 
const buttonVariants = cva(
  // Bazowe klasy — wspólne dla wszystkich wariantów
  'inline-flex items-center justify-center gap-2 rounded-lg font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        primary:
          'bg-brand-600 text-white hover:bg-brand-700 focus-visible:ring-brand-500',
        secondary:
          'bg-surface-secondary text-content hover:bg-brand-100 focus-visible:ring-brand-500',
        destructive:
          'bg-red-600 text-white hover:bg-red-700 focus-visible:ring-red-500',
        ghost:
          'text-content-secondary hover:bg-surface-secondary focus-visible:ring-brand-500',
        link: 'text-brand-600 underline-offset-4 hover:underline focus-visible:ring-brand-500',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-6 text-base',
        icon: 'h-10 w-10',
      },
    },
    defaultVariants: {
      variant: 'primary',
      size: 'md',
    },
  },
)
 
export interface ButtonProps
  extends ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean
}
 
const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ asChild = false, className, variant, size, type, ...props }, ref) => {
    const Component = asChild ? Slot.Root : 'button'
 
    return (
      <Component
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        type={asChild ? undefined : (type ?? 'button')}
        {...props}
      />
    )
  },
)
 
Button.displayName = 'Button'
 
export { Button, buttonVariants }

Użycie — z pełnym autocompletem:

Code
<Button variant="primary" size="lg">Zapisz</Button>
<Button variant="destructive">Usuń</Button>
<Button variant="ghost" size="icon"><TrashIcon /></Button>
<Button variant="link">Dowiedz się więcej</Button>
 
{/* asChild przekazuje style i zachowanie do jedynego elementu potomnego */}
<Button asChild><a href="/kontakt">Skontaktuj się</a></Button>
 
{/* Nadpisanie klasy — cn() rozwiąże konflikty */}
<Button className="w-full">Pełna szerokość</Button>

Komponent Input z wariantami w design systemie

Code
// components/ui/input.tsx
import { cva, type VariantProps } from 'class-variance-authority'
import { forwardRef, useId, type InputHTMLAttributes } from 'react'
import { cn } from '@/lib/utils'
 
const inputVariants = cva(
  'w-full rounded-lg border bg-white px-3 py-2 text-sm transition-colors placeholder:text-gray-400 focus:outline-none focus:ring-2 focus:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50',
  {
    variants: {
      variant: {
        default: 'border-gray-300 focus:ring-blue-500',
        error: 'border-red-500 focus:ring-red-500 text-red-900',
      },
      inputSize: {
        sm: 'h-8 text-xs',
        md: 'h-10 text-sm',
        lg: 'h-12 text-base',
      },
    },
    defaultVariants: {
      variant: 'default',
      inputSize: 'md',
    },
  },
)
 
interface InputProps
  extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'>,
    VariantProps<typeof inputVariants> {
  label?: string
  error?: string
}
 
const Input = forwardRef<HTMLInputElement, InputProps>(
  ({ className, variant, inputSize, label, error, id, ...props }, ref) => {
    const generatedId = useId()
    const inputId = id ?? props.name ?? generatedId
 
    return (
      <div className="space-y-1">
        {label && (
          <label
            htmlFor={inputId}
            className="text-sm font-medium text-gray-700"
          >
            {label}
          </label>
        )}
        <input
          id={inputId}
          className={cn(
            inputVariants({
              variant: error ? 'error' : variant,
              inputSize,
              className,
            }),
          )}
          ref={ref}
          aria-invalid={error ? true : undefined}
          aria-describedby={error ? `${inputId}-error` : undefined}
          {...props}
        />
        {error && (
          <p
            id={`${inputId}-error`}
            className="text-sm text-red-600"
            role="alert"
          >
            {error}
          </p>
        )}
      </div>
    )
  },
)
 
Input.displayName = 'Input'
export { Input }

Radix UI jako baza dostępnych komponentów

Radix UI to zestaw headless komponentów, które dostarczają zachowanie i mechanizmy dostępności (zarządzanie focusem, ARIA, klawiatura), ale nie narzucają przy tym stylów. Sami dodajemy wygląd przez Tailwind, a przy użyciu prymitywów rozwiązujemy trudną część techniczną, nadając także poprawne etykiety, zrozumiałą treść i kontrast.

Code
// components/ui/modal.tsx
'use client'
 
import { Dialog } from 'radix-ui'
import { X } from 'lucide-react'
import type { ReactNode } from 'react'
import { cn } from '@/lib/utils'
 
interface ModalProps {
  open: boolean
  onOpenChange: (open: boolean) => void
  title: string
  description: string
  children: ReactNode
  className?: string
}
 
export function Modal({
  open,
  onOpenChange,
  title,
  description,
  children,
  className,
}: ModalProps) {
  return (
    <Dialog.Root open={open} onOpenChange={onOpenChange}>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 z-50 bg-black/50 transition-opacity data-[state=closed]:opacity-0 data-[state=open]:opacity-100" />
        <Dialog.Content
          className={cn(
            'fixed top-1/2 left-1/2 z-50 w-full max-w-lg -translate-x-1/2 -translate-y-1/2 rounded-xl bg-white p-6 shadow-xl',
            'transition-[opacity,scale] data-[state=closed]:scale-95 data-[state=closed]:opacity-0 data-[state=open]:scale-100 data-[state=open]:opacity-100',
            className,
          )}
        >
          <Dialog.Title className="text-lg font-semibold">{title}</Dialog.Title>
 
          <Dialog.Description className="mt-1 text-sm text-gray-500">
            {description}
          </Dialog.Description>
 
          <div className="mt-4">{children}</div>
 
          <Dialog.Close className="absolute top-4 right-4 rounded-sm opacity-70 hover:opacity-100">
            <X className="h-4 w-4" />
            <span className="sr-only">Zamknij</span>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  )
}

Radix automatycznie obsługuje zamykanie klawiszem Escape, blokadę focusu wewnątrz modala i jego przywracanie po zamknięciu. Dialog.Title oraz Dialog.Description dostarczają powiązania potrzebne czytnikom ekranu. Nie pomijaj tytułu; jeśli świadomie rezygnujesz z opisu, zgodnie z dokumentacją ustaw na Dialog.Content wartość aria-describedby={undefined}.

Komponent Badge z CVA

Code
// components/ui/badge.tsx
import { cva, type VariantProps } from 'class-variance-authority'
import type { HTMLAttributes } from 'react'
import { cn } from '@/lib/utils'
 
const badgeVariants = cva(
  'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium transition-colors',
  {
    variants: {
      variant: {
        default: 'bg-gray-100 text-gray-800',
        success: 'bg-green-100 text-green-800',
        warning: 'bg-yellow-100 text-yellow-800',
        error: 'bg-red-100 text-red-800',
        info: 'bg-blue-100 text-blue-800',
      },
    },
    defaultVariants: {
      variant: 'default',
    },
  },
)
 
interface BadgeProps
  extends HTMLAttributes<HTMLSpanElement>,
    VariantProps<typeof badgeVariants> {}
 
export function Badge({ className, variant, ...props }: BadgeProps) {
  return (
    <span className={cn(badgeVariants({ variant, className }))} {...props} />
  )
}

Tokeny design systemu w Tailwind CSS

W Tailwind CSS 4 podstawowym sposobem definiowania tokenów są zmienne @theme w głównym pliku CSS. To one tworzą odpowiadające im klasy narzędziowe:

Code
/* app/globals.css */
@import 'tailwindcss';
 
@theme {
  --color-brand-50: #eff6ff;
  --color-brand-100: #dbeafe;
  --color-brand-500: #3b82f6;
  --color-brand-600: #2563eb;
  --color-brand-700: #1d4ed8;
  --color-brand-900: #1e3a5f;
 
  --color-surface: #ffffff;
  --color-surface-secondary: #f9fafb;
  --color-content: #111827;
  --color-content-secondary: #6b7280;
 
  --radius-default: 0.5rem;
  --radius-lg: 0.75rem;
  --radius-xl: 1rem;
 
  --text-heading-1: 2.25rem;
  --text-heading-1--line-height: 2.5rem;
  --text-heading-1--font-weight: 700;
  --text-body: 1rem;
  --text-body--line-height: 1.5rem;
  --text-caption: 0.75rem;
  --text-caption--line-height: 1rem;
}

Teraz zamiast text-blue-600 używasz text-brand-600, a tokeny są dostępne także jako zwykłe zmienne CSS, np. var(--color-brand-600). W projekcie z Tailwind CSS 3 analogiczny motyw definiuje się w tailwind.config, ale nie jest to już główna ścieżka konfiguracji Tailwinda 4. Jeśli wartości mają zmieniać się między jasnym i ciemnym motywem, trzymaj właściwe kolory w zwykłych zmiennych CSS, a następnie mapuj je na nazwy @theme inline.

Organizacja plików design systemu w Next.js

Code
components/
└── ui/
    ├── button.tsx
    ├── input.tsx
    ├── badge.tsx
    ├── card.tsx
    ├── modal.tsx
    ├── tooltip.tsx
    ├── tabs.tsx
    ├── dropdown-menu.tsx
    └── index.ts          ← Opcjonalny publiczny interfejs modułu
Code
// components/ui/index.ts
export { Button, buttonVariants } from './button'
export { Input } from './input'
export { Badge } from './badge'
export { Card } from './card'
export { Modal } from './modal'

Plik zbiorczy jest wygodny, ale też nie jest obowiązkowy. W kodzie trafiającym do Client Components bezpośrednie importy, np. @/components/ui/button, ułatwiają kontrolę granic klient–serwer i analizę paczki. Niezależnie od stylu importu eksportuj tylko elementy należące do publicznego API design systemu.

Dokumentacja i testy komponentów

Sam katalog components/ui nie czyni jeszcze systemu projektowego dojrzałym. Każdy komponent powinien posiadać udokumentowane warianty, stany (takie jak hover, focus-visible, disabled, błędy czy stany ładowania) oraz przykłady poprawnego użycia. Możesz utrzymywać tę dokumentację w Storybooku lub w wydzielonej sekcji aplikacji i kluczowe jest, aby zespół miał jedno, centralne miejsce prezentujące publiczne API wszystkich komponentów.

Testuj przede wszystkim własne kontrakty, przykładowo, czy Button przekazuje atrybuty i ref, czy błąd Input jest powiązany przez aria-describedby, czy modal ma tytuł i można go obsłużyć klawiaturą. Do testów zachowania wystarczą Testing Library i runner używany w projekcie, a automatyczny audyt axe warto uzupełnić ręcznym testem klawiaturą. Testy regresji wizualnej pomagają wykryć niezamierzone zmiany tokenów i wariantów, których zwykły test DOM nie zauważy.

Bezpieczne automatyzacje procesów i agenci AI w n8n, Make i Claude.
Automatyzacja AI

Często zadawane pytania

Czym to się różni od shadcn/ui?

Wariant Radix w shadcn/ui korzysta z bardzo podobnego stosu: Tailwind, CVA i prymitywy Radix. shadcn/ui obsługuje jednak także Base UI, więc nie każdy nowy projekt używa już Radix. Różnica pozostaje w modelu dystrybucji: CLI dodaje kod komponentów do Twojego projektu, a nie dostarcza zamkniętej biblioteki. Budowanie od zera daje większą kontrolę nad API, ale start od shadcn/ui i późniejsza modyfikacja komponentów również jest sensowną ścieżką.

Czy mogę użyć CVA bez Radix?

Tak. CVA to narzędzie wyłącznie do zarządzania wariantami komponentów i działa z dowolnym elementem — przyciskiem, badge'em, kartą. Radix dokłada warstwę dostępności i zachowania (focus, ARIA, klawiatura), ale nie jest wymagany. Proste, statyczne komponenty bez interakcji nie potrzebują Radix; sięgasz po niego dopiero przy modalach, dropdownach czy tabach, gdzie dostępność jest trudna do zrobienia ręcznie.

Czy design system spowalnia bundle?

Może, zwłaszcza gdy wiele interaktywnych prymitywów Radix trafia do Client Components. Tailwind generuje CSS podczas builda, ale CVA, tailwind-merge i kod interakcji Radix mogą znaleźć się w paczce klienta. Importuj tylko używane elementy, utrzymuj granice use client możliwie nisko i mierz wynik analizatorem paczki zamiast zakładać, że narzut zawsze będzie pomijalny.

Po co helper cn() zamiast zwykłego łączenia klas?

Bo samo sklejanie stringów klas Tailwinda prowadzi do konfliktów. Gdy w jednym miejscu masz bg-red-500, a w drugim nadpisujesz bg-blue-500, bez tailwind-merge wynik jest nieprzewidywalny — zależy od kolejności w CSS, nie w kodzie. cn() łączy clsx (warunkowe klasy) z tailwind-merge, dzięki czemu ostatnia klasa danej właściwości zawsze wygrywa, tak jak intuicyjnie tego oczekujesz.

Od ilu komponentów zacząć budowę design systemu?

Od minimalnego zestawu, który faktycznie wykorzystasz — zwykle Button, Input, Card i Badge. To wystarcza, żeby ujednolicić większość interfejsu, a jednocześnie nie wpadasz w pułapkę budowania komponentów „na zapas", których nikt nie użyje. Design system rozbudowuj reaktywnie: gdy trzeci raz piszesz ten sam wzorzec ręcznie, to znak, że czas zrobić z niego komponent.

O autorze

Maciej Sala

Maciej Sala — Product Manager i Frontend Developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwijam własne projekty.

Moje artykuły

Pomagam przekładać takie tematy na konkretne wdrożenia w frontendzie, SEO, analityce i procesie produktowym.

Skontaktuj się ze mną

Biblioteka wiedzy na temat Next.js

Czytaj dalej

Zobacz więcej wpisów
Migracja z Elementora i Divi do Astro lub Next.js

WordPress z Elementorem albo Divi to najszybszy sposób, żeby postawić stronę, ale też najszybszy, żeby ją spowolnić, akurat kiedy zacznie zarabiać. Wizualny edytor, który był początkowo wygodny, z czasem będzie ciągnął w dół Core Web Vitals , a z nimi pozycje w Google i konwersję. Ten artykuł pokazuje, jak zdiagnozować problem, wybrać między Astro a Next.js i przeprowadzić migrację bez utraty wypracowanego z trudem SEO.

Maciej Sala

Maciej Sala

Founder StriveLab

Jak osiągnąć 100/100 w Lighthouse Performance w Next.js? Case study

Mamy tu typową stronę usługową zbudowaną w Next.js, wyposażoną w Google Analytics, Google Tag Manager , prosty formularz kontaktowy, galerię zdjęć i animacje. Na początku testy PageSpeed Insights pokazały wyniki: 67/100 na urządzeniach mobilnych i 89/100 na komputerach stacjonarnych.

Maciej Sala

Maciej Sala

Founder StriveLab

TypeScript w React bez bólu: 7 wzorców do produkcyjnych komponentów

W tym artykule pokazuję siedem wzorców, które sam stosuję produkcyjnie — w StriveLab https://strivelab.pl/tworzenie-stron-internetowych/react/ , Army Builder https://army-builder.com , i u klientów. Każdy z nich rozwiązuje konkretny problem, który w 2026 roku masz rozwiązywać lepiej niż pięć lat temu, bo TypeScript i React dostały nowe narzędzia.

Maciej Sala

Maciej Sala

Founder StriveLab