UX/UI Guidelines

Cel

Przewodnik dla projektowania interfejsu użytkownika - design system, dostępność, responsywność, animacje, wzorce UI zgodne ze standardami 2025.

Kiedy Używać Tego Skilla

• •Projektowanie nowych komponentów UI
• •Implementacja dostępności (WCAG 2.2, ARIA)
• •Responsive design i container queries
• •Animacje i przejścia
• •Formularze i modale
• •Mobile UX
• •Nawigacja, tabele, wyszukiwanie, onboarding

Quick Start

Checklist Nowego Komponentu UI

• • Mobile-first styling (zaczynaj od mobile)
• • Container queries dla komponentów (@container)
• • Focus visible dla nawigacji klawiaturą
• • ARIA labels dla elementów interaktywnych
• • Touch targets min 44x44px (WCAG 2.2)
• • prefers-reduced-motion dla animacji
• • Contrast ratio min 4.5:1 (WCAG AA)
• • Dynamic viewport units (min-h-dvh)

Checklist Formularza

• • Labels powiązane z inputami (htmlFor)
• • Komunikaty błędów z role="alert"
• • Walidacja inline (nie tylko po submit)
• • Loading state z useTransition lub mutation
• • Success/error feedback (Sonner toast)
• • Focus na pierwszym błędzie
• • aria-describedby dla error messages

Design System

Paleta Kolorów (OKLCH)

OKLCH zapewnia lepszą percepcję jasności niż HSL:

/* globals.css - Tailwind v4 */
@theme {
    /* Brand */
    --color-primary: oklch(0.55 0.25 264);        /* Niebieski CTA */
    --color-primary-foreground: oklch(1 0 0);     /* Biały tekst */
    --color-accent: oklch(0.65 0.2 160);          /* Zielony accent */
    --color-destructive: oklch(0.55 0.25 27);     /* Czerwony błędy */

    /* Neutral */
    --color-background: oklch(1 0 0);             /* Białe tło */
    --color-foreground: oklch(0.2 0.02 260);      /* Główny tekst */
    --color-muted: oklch(0.96 0.01 260);          /* Drugie tła */
    --color-muted-foreground: oklch(0.55 0.02 260); /* Drugie teksty */
    --color-border: oklch(0.9 0.01 260);          /* Obramowania */
}

Skala Typografii

Spacing

4px  = p-1, gap-1
8px  = p-2, gap-2
12px = p-3, gap-3
16px = p-4, gap-4
24px = p-6, gap-6
32px = p-8, gap-8

Pełny Przewodnik: resources/design-system.md

Topic Guides

Dostępność (WCAG 2.2)

Wymagania:

• •Contrast ratio min 4.5:1 dla tekstu
• •Focus visible i nie zasłonięty (2.4.11 Focus Not Obscured)
• •Touch targets min 44x44px (2.5.8 Target Size)
• •ARIA labels dla ikon/przycisków
• •Nagłówki w poprawnej hierarchii

Kluczowe Wzorce:

• •aria-label dla przycisków z ikonami
• •role="alert" + aria-live="polite" dla błędów
• •sr-only dla tekstu screen reader only
• •Focus trap w modalach (react-focus-lock)

Pełny Przewodnik: resources/accessibility.md

Responsive Design

Mobile-First + Container Queries:

// Tailwind v4 - container queries
<div className="@container">
    <div className="flex flex-col @md:flex-row @lg:gap-6">
        {/* Reaguje na rozmiar kontenera, nie viewportu */}
    </div>
</div>

Breakpointy (viewport):

• •sm: 640px - Małe tablety
• •md: 768px - Tablety
• •lg: 1024px - Desktop

Container queries (komponent):

• •@sm: 320px
• •@md: 448px
• •@lg: 512px

Dynamic Viewport Units:

/* Uwzględnia mobile browser chrome */
min-h-dvh  /* dynamic viewport height */
min-h-svh  /* small viewport height */
min-h-lvh  /* large viewport height */

Pełny Przewodnik: resources/responsive-design.md

Animacje

Framer Motion Wzorce:

• •Fade in dla wchodzących elementów
• •Staggered lists dla grup
• •AnimatePresence dla mount/unmount

View Transitions API (2025):

function handleNavigation() {
    if (!document.startViewTransition) {
        navigate(path);
        return;
    }
    document.startViewTransition(() => navigate(path));
}

Kluczowe Zasady:

• •prefers-reduced-motion - wymagane
• •Krótkie animacje (150-300ms)
• •Unikaj animacji layoutu (CLS)
• •CSS animations > JS gdy możliwe

Pełny Przewodnik: resources/animations.md

Komponenty UX

Wzorce:

• •Modale z focus trap (react-focus-lock)
• •Formularze z inline validation
• •Toast notifications (Sonner)
• •Loading states (useTransition)
• •Optimistic updates (useOptimistic)

Pełny Przewodnik: resources/component-ux.md

UI Patterns

Nawigacja:

• •Tabs (URL-synced)
• •Breadcrumbs z aria-label
• •Pagination (number + cursor-based)

Wyświetlanie danych:

• •Responsive tables (cards na mobile)
• •Empty states
• •Skeleton loading

Wyszukiwanie i filtrowanie:

• •Debounced search input
• •Filter chips
• •URL state sync

Onboarding:

• •Multi-step wizard ze StepIndicator
• •Feature spotlight/tooltip
• •Progress save (localStorage)

Pełny Przewodnik: resources/patterns.md

Przykład: Komponent Button (2025)

import { useTransition } from 'react';
import { Button } from '@/components/ui/button';
import { Loader2 } from 'lucide-react';
import { cn } from '@/lib/utils';

interface ActionButtonProps {
    onClick: () => Promise<void>;
    children: React.ReactNode;
    disabled?: boolean;
}

export function ActionButton({ onClick, children, disabled }: ActionButtonProps) {
    const [isPending, startTransition] = useTransition();

    const handleClick = () => {
        startTransition(async () => {
            await onClick();
        });
    };

    return (
        <Button
            onClick={handleClick}
            disabled={disabled || isPending}
            className={cn(
                "inline-flex items-center justify-center gap-2",
                "min-h-11 px-4",  // 44px touch target
                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
                "transition-colors duration-200"
            )}
            aria-busy={isPending}
        >
            {isPending && (
                <Loader2 className="h-4 w-4 animate-spin" aria-hidden="true" />
            )}
            {children}
        </Button>
    );
}

Navigation Guide

Główne Zasady 2025

1. •Mobile-First + Container Queries
2. •WCAG 2.2 jako minimum (nowe: focus-not-obscured, target size)
3. •OKLCH colors zamiast HSL
4. •Dynamic viewport (dvh) zamiast vh
5. •Focus States widoczne i nie zasłonięte
6. •Touch Targets min 44x44px
7. •prefers-reduced-motion obowiązkowo
8. •useTransition dla loading states (nie useState)
9. •View Transitions dla nawigacji (z fallbackiem)

Powiązane Skills

• •tailwind-react-guidelines: Komponenty React, Tailwind v4