UX aplikacji z Claude - jak projektować interfejsy AI które działają i budują zaufanie

Seria Claude Code · JSystems

Użytkownik czeka 8 sekund na odpowiedź AI i myśli że coś się zawiesiło. Zamyka zakładkę. Tracisz klienta. Tego da się uniknąć - i pokażemy Ci jak.

Najlepszy model AI w aplikacji z kiepskim UX to przepis na frustrację użytkownika. Aplikacje z LLM mają unikalne wyzwania designu: model odpowiada z opóźnieniem, może się mylić, odpowiedzi są nieprzewidywalnej długości, a użytkownik nie wie jak formulować zapytania. Ten artykuł zbiera lekcje z realnych wdrożeń aplikacji AI - co działa, co nie i dlaczego.

Problem #1: Latencja - użytkownik nie wie czy coś się dzieje

Claude Sonnet odpowiada typowo w 2-8 sekund. Dla użytkownika przyzwyczajonego do natychmiastowych odpowiedzi - to wieczność. Badania UX pokazują że po 3 sekundach oczekiwania użytkownicy zaczynają wątpić czy aplikacja działa.

Przed i po - konkretny przykład:

Streaming - kluczowy pattern dla AI

Nigdy nie czekaj na pełną odpowiedź przed wyświetleniem. Streaming daje użytkownikowi sygnał że coś się dzieje i znacząco poprawia perceived performance - postrzeganą szybkość, nawet jeśli całkowity czas jest taki sam.

Poniżej implementacja streamingu w React - krok po kroku:

Krok 1: Stan komponentu przechowuje aktualny tekst i flagę czy Claude wciąż odpowiada.

Krok 2: Otwieramy połączenie strumieniowe z backendem gdy komponent się pojawi.

Krok 3: Czytamy dane ze strumienia w kawałkach i na bieżąco dodajemy do wyświetlanego tekstu.

Krok 4: Migający kursor pokazuje że Claude wciąż odpowiada - znika gdy skończy.

// React + streaming Claude API
// React to biblioteka JavaScript do budowania interfejsów użytkownika
import { useState, useEffect } from 'react';

// TypeScript: { prompt: string } to typ parametru - musi być stringiem
function ChatMessage({ prompt }: { prompt: string }) {
  // KROK 1: Stan komponentu
  // text = aktualny tekst odpowiedzi (pusty na starcie)
  const [text, setText] = useState('');
  // isLoading = czy Claude wciąż odpowiada (true = tak, pokazuj kursor)
  const [isLoading, setIsLoading] = useState(true);

  // KROK 2: Połączenie strumieniowe gdy komponent się pojawi
  useEffect(() => {
    const stream = async () => {
      // Wywołujemy nasz backend który proxy'uje do Claude API
      const response = await fetch('/api/claude', {
        method: 'POST',
        body: JSON.stringify({ prompt }),
      });

      // KROK 3: Czytamy dane ze strumienia kawałek po kawałku
      // response.body.getReader() = czytnik strumienia danych binarnych
      const reader = response.body!.getReader();
      // TextDecoder zamienia bajty na tekst UTF-8
      const decoder = new TextDecoder();

      // Pętla czytająca dane ze strumienia
      while (true) {
        const { done, value } = await reader.read();
        if (done) { setIsLoading(false); break; } - // Koniec strumienia
        // prev => prev + ... = dodaj nowy fragment do istniejącego tekstu
        setText(prev => prev + decoder.decode(value));
      }
    };
    stream();
  }, [prompt]); - // Zależność: uruchom gdy prompt się zmieni

  return (
    <div className="message">
      {text}
      {/* KROK 4: Migający kursor pokazuje że Claude wciąż odpowiada */}
      {isLoading && <span className="cursor-blink">▊</span>}
    </div>
  );
}

Po wdrożeniu: otwórz DevTools (F12) --> zakładka Network. Wywołaj zapytanie do Claude. Powinieneś zobaczyć request do /api/claude z Type "EventStream" lub "Fetch" który rośnie w czasie - to znak że streaming działa.

Skeleton loading i progress indicators

• Pokaż "Claude myśli..." z animowanymi kropkami przez pierwsze 500ms - użytkownik wie że aplikacja żyje
• Dla długich zadań (analiza dokumentu): progress bar z etapami ("Czytam dokument... Analizuję... Przygotowuję odpowiedź...") - każda zmiana fazy redukuje niepewność
• Optymistyczne UI: pokaż akcję użytkownika natychmiast (np. "Twoja wiadomość"), odpowiedź AI pojawia się gdy jest gotowa

Problem #2: Użytkownicy nie wiedzą co pisać

Puste pole tekstowe z "Zapytaj mnie o cokolwiek" to najgorszy UX dla AI. Użytkownicy paraliżują się - "Co mogę tu wpisać?", "Czy zrozumie moje pytanie?", "Jak to sformułować?". To zjawisko nazywa się blank page syndrome i dotyka nawet zaawansowanych użytkowników.

Przed i po - konkretny przykład:

Suggested prompts - zawsze, bez wyjątków

Krok 1: Przygotuj zestaw sugestii dla każdego kontekstu (kod, dokument, ogólny).

Krok 2: Wyświetl je jako klikalne przyciski gdy pole jest puste.

Krok 3: Po kliknięciu - wstaw sugestię do pola lub wyślij od razu. Użytkownik może edytować przed wysłaniem.

// KROK 1: Sugerowane pytania - zmieniaj kontekstowo
const SUGGESTIONS = {
  // Tryb "kod" - użytkownik wkleił lub wskazał plik kodu
  'code': [
    'Wyjaśnij ten kod',
    'Znajdź błędy',
    'Napisz testy',
    'Zoptymalizuj wydajność'
  ],
  // Tryb "dokument" - użytkownik załadował PDF lub tekst
  'document': [
    'Podsumuj w 5 punktach',
    'Jakie są kluczowe ryzyka?',
    'Porównaj z poprzednią wersją',
    'Przetłumacz na angielski'
  ]
};

// KROK 2 i 3: Komponent React wyświetlający przyciski z sugestiami
function PromptSuggestions({ context, onSelect }) {
  return (
    <div className="suggestions">
      {/* Dla każdej sugestii - klikalny przycisk */}
      {SUGGESTIONS[context].map(s => (
        // onSelect(s) = gdy użytkownik kliknie, wstaw sugestię do pola tekstowego
        <button key={s} onClick={() => onSelect(s)}>{s}</button>
      ))}
    </div>
  );
}

Placeholder jako instrukcja, nie zachęta

Zamiast "Wpisz wiadomość..." --> "Np: Znajdź błędy w tym kodzie / Podsumuj ten dokument / Co oznacza ten błąd?". Placeholder pokazuje konkretne przykłady, nie abstrakcyjne możliwości - użytkownik widzi format i zakres.

Problem #3: Model może się mylić - jak to komunikować

Claude halucynuje. Nie często, ale zdarza się - szczególnie dla danych po jego dacie treningowej lub dla bardzo specyficznych faktów. Ukrywanie tego niszczy zaufanie gdy użytkownik odkryje błąd. Transparentność jest kluczem do długotrwałego zaufania.

Przed i po - konkretny przykład komunikacji halucynacji:

• Confidence indicators: "Na podstawie Twoich danych..." (wysoka pewność - mamy dokumenty) vs "Zakładam że..." (średnia) vs "Nie jestem pewny, ale..." (niska - ryzyko halucynacji)
• Source attribution: w RAG zawsze pokaż skąd pochodzi informacja ("Według dokumentu 'Regulamin 2026', str. 12..."). Użytkownik może samodzielnie sprawdzić
• Uncertainty prompting: skonfiguruj Claude żeby przyznawał się do niepewności: "Jeśli nie jesteś pewny odpowiedzi - powiedz to wyraźnie zamiast zgadywać."
• Easy feedback: przycisk po każdej odpowiedzi - zbieraj dane o jakości, używaj do poprawy systemu promptów

Problem #4: Obsługa błędów widoczna dla użytkownika

Techniczne błędy API nigdy nie powinny trafiać bezpośrednio do użytkownika. "anthropic.APIStatusError: 529" nie mówi mu nic użytecznego - tylko wywołuje panikę. Każdy błąd powinien mówić użytkownikowi co ma zrobić, nie co poszło nie tak technicznie.

Przed i po - obsługa błędu rate limiting:

// NIE RÓB tak - techniczny błąd trafia bezpośrednio do interfejsu
catch (error) {
  setError(error.message); // "anthropic.APIStatusError: 529" - użytkownik nie wie co to znaczy
}

// RÓB tak - przyjazny komunikat dla użytkownika + techniczne logi dla dewelopera
catch (error) {
  if (error instanceof RateLimitError) {
    // Zbyt wiele żądań - użytkownik dostaje prostą instrukcję co zrobić
    setError('Asystent jest bardzo zajęty. Spróbuj za kilka sekund.');
  } else if (error instanceof APIConnectionError) {
    // Problem z siecią - sugeruj sprawdzenie połączenia
    setError('Problem z połączeniem. Sprawdź internet i spróbuj ponownie.');
  } else {
    // Nieznany błąd - ogólny komunikat + zaloguj technikalia
    setError('Coś poszło nie tak. Odśwież stronę jeśli problem się powtarza.');
    // logger.error loguje szczegóły dla dewelopera (widoczne w logach serwera)
    logger.error('Claude API error:', error);
  }
}

Problem #5: Długie odpowiedzi - czytelność i nawigacja

Claude lubi długie, szczegółowe odpowiedzi. W UI często to problem - użytkownik widzi ścianę tekstu i nie wie gdzie patrzeć. Wzorce które działają:

• Progressive disclosure: pokaż podsumowanie + "Zobacz więcej" dla szczegółów. Większość użytkowników chce skrótu, nie pełnego elaboratu
• Markdown rendering: Claude domyślnie zwraca markdown (tekst z **pogrubieniami**, # nagłówkami, - listami). Musisz go renderować - surowe gwiazdki w UI wyglądają fatalnie. Biblioteki: react-markdown (React), marked.js (vanilla JS)
• Code highlighting: dla odpowiedzi z kodem - syntax highlighting (Prism.js lub highlight.js). Kolorowy kod jest 3× czytelniejszy niż czarno-biały
• Copy button: na każdym bloku kodu - użytkownicy oczekują że mogą skopiować jednym kliknięciem. Bez tego wielokrotnie zaznaczają myszką i klną

# wdrożenie produkcyjne
npm run build && \
  docker push registry/app:latest

Problem #6: Kontekst konwersacji - zarządzanie historią

• Pokaż rozmowę jako wątki - nie stack scrollowalnych wiadomości gdy jest ich 50. Długa lista wiadomości jest nieczytelna
• Możliwość edycji promptu - "Edytuj i wyślij ponownie" zamiast przepisywania od zera. Oszczędza czas i frustrację
• Restore context - użytkownik wraca po tygodniu, pokaż mu krótkie podsumowanie poprzedniej rozmowy. Nie musi czytać 50 wiadomości żeby wiedzieć gdzie skończył
• Limit długości konwersacji - po X wiadomościach zaproponuj "Zacznij nową rozmowę" żeby nie tracić jakości. Długi kontekst = Claude "zapomina" co było na początku (limit okna kontekstowego)

Wzorzec: Human-in-the-loop dla krytycznych akcji

Human-in-the-loop to pattern gdzie dla ważnych, nieodwracalnych akcji - agent musi uzyskać potwierdzenie od człowieka zanim je wykona. Zasada: im bardziej nieodwracalna akcja, tym silniejsze potwierdzenie potrzebne.

// Komponent React pokazujący prośbę o potwierdzenie akcji agenta
// onConfirm i onReject to funkcje zwrotne (callbacks) wywoływane po kliknięciu
function AgentAction({ action, onConfirm, onReject }) {
  return (
    <div className="action-approval">
      <p>Agent chce wykonać:</p>
      {/* action.description = opis konkretnej akcji w czytelnym języku */}
      <code>{action.description}</code>
      <div className="buttons">
        <button onClick={onConfirm} className="btn-approve">
          Zatwierdz
        </button>
        <button onClick={onReject} className="btn-reject">
          Odrzuc
        </button>
      </div>
    </div>
  );
}
// Używaj tego wzorca gdy agent chce: wysłać email, zapisać do bazy, wywołać zewnętrzne API

Częste błędy przy projektowaniu UX dla AI

Checklist UX przed wdrożeniem aplikacji z Claude

Przejdź przez tę listę przed każdym wdrożeniem. Każdy niezaznaczony punkt to potencjalna frustracja użytkownika:

• Streaming jest włączony - użytkownik widzi odpowiedź w czasie rzeczywistym
• Loader pojawia się natychmiast po kliknięciu Wyślij
• Są suggested prompts lub przykłady - użytkownik wie od czego zacząć
• Błędy API mają przyjazne komunikaty dla użytkownika (nie kody błędów)
• Markdown jest renderowany - nie surowy tekst z gwiazdkami i kratkami
• Kod ma syntax highlighting i przycisk kopiowania
• Długie odpowiedzi mają progressive disclosure (podsumowanie + "więcej")
• Krytyczne akcje agenta wymagają potwierdzenia (human-in-the-loop)
• Jest mechanizm feedbacku (thumbs up/down lub podobny)
• Stany: loading (ładowanie), success (sukces), error (błąd) są wyraźnie komunikowane
• Mobile działa poprawnie - szczególnie klawiatura nie zasłania pola input

Kiedy Twoja aplikacja AI reaguje natychmiast, prowadzi użytkownika za rękę i komunikuje błędy jak przyjaciel - użytkownicy wracają. Dobry UX zamienia jednorazowych odwiedzających w lojalnych klientów, a Twój produkt wyróżnia się wśród morza przeciętnych aplikacji AI.