Frontend Design — Stellar dApp UI

Build visually distinctive Stellar dApp frontends that integrate wallet connection, contract interaction, and transaction flows — all while avoiding generic "AI slop" aesthetics.

When to Use

• Designing wallet connect / disconnect UI that stands out
• Displaying on-chain data (balances, token info, contract state) beautifully
• Building transaction confirmation flows with loading + success states
• Creating a cohesive dApp dashboard with contract read/write widgets
• Styling agentic kit components (useStellarData, useContract, useWallet)
• Any Stellar frontend task where visual polish matters

Design Thinking

Before writing UI code, commit to a bold aesthetic direction:

• Purpose: What does this interface do? Who uses it — traders, devs, collectors?
• Tone: Pick an extreme — brutalist dark, luxe-light editorial, retro-terminal, futuristic glassmorphism, industrial monochrome, playful neo-brutalism.
• Blockchain UX constraints: Wallet not connected, waiting for confirmation, tx pending, tx confirmed, error states — each needs its own visual language.
• Differentiation: What makes this UNFORGETTABLE? A custom loading spinner made from Stellar icons? Animated transaction history? A gradient that shifts with each new block?

CRITICAL: Execute with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.

Stellar dApp UI Patterns

Pattern 1 — Wallet Connection

Every dApp starts with wallet connect. Design for the full lifecycle:

Disconnected → Connecting → Connected → Disconnecting

Pattern 2 — Transaction Flow

A tx has 4 phases. Each needs distinct UI:

Simulate → Sign → Submit → Confirm

Pattern 3 — Contract Data Display

For read-only contract state (useContract().read()):

• Numeric values: Format with proper decimal places, show loading skeleton
• Addresses: Truncate with G...abcd pattern, link to Stellar Expert
• Timestamps: Relative ("2 min ago") + tooltip with absolute
• Enums/status: Badge with color-coded status indicator
• Empty state: Never show "0" without context — use "No tokens yet" with illustration

Pattern 4 — Error States

Blockchain errors are frequent. Design them in:

• Wallet not connected: Context-aware prompt, not a red error box
• User rejected: Subtle dismissal, no alarm
• Insufficient XLM: Actionable — "You need at least 1.1 XLM for this transaction"
• Network mismatch: Prominent banner with one-click network switch
• RPC timeout: Retry button with exponential backoff indicator

Tailwind CSS — Mandatory Styling

All UI code must use Tailwind CSS (v4+, bundled with the scaffold). No CSS modules, no styled-components, no inline styles for layout or color. Use tailwindcss for every design choice — typography, spacing, color, layout, animation.

Tailwind Patterns for dApps

Customizing the dApp Theme

In tailwind.config.ts, define semantic tokens for your dApp's brand:

theme: {
  extend: {
    colors: {
      stellar: {   // Stellar brand integration
        blue:  "#3e5b9c",
        purple: "#7c3aed",
      },
    },
    fontFamily: {
      mono: ["JetBrains Mono", "Fira Code", "monospace"], // for addresses + data
    },
    keyframes: {
      "slide-bar": { "0%": { width: "0%" }, "100%": { width: "100%" } },
    },
    animation: {
      "slide-bar": "slide-bar 5s ease-in-out",
    },
  },
}

Dark Mode

Every dApp must support both light and dark modes using Tailwind's dark: variant:

<div className="bg-white dark:bg-gray-950 text-gray-900 dark:text-gray-100">

Never hardcode colors without a dark mode counterpart.

Agentic Kit Integration

All Stellar data flows through the agentic kit hooks. Every UI component must use these — never raw RPC.

Component → Hook Mapping

Design Rules for Hook Data

1. Show loading skeleton (not spinner) while getBalances or read() resolves
2. Show last-updated timestamp for cached on-chain data
3. Always handle error from contract.data.error or data.error
4. Use addressToScVal / i128ToScVal from lib/stellar-config.ts for args
5. Never display raw ScVal — always convert via scvalToString / scvalToNumber
6. After a write() completes, auto-refresh relevant read() data

Source Files (published with this skill)

Working Examples

Wallet connect with balance badge

function StellarStatusBar() {
  const { address, connect, disconnect, getBalances } = useWallet();
  return address ? (
    <div className="flex items-center gap-3 px-4 py-2 border-b bg-card">
      <div className="w-2 h-2 rounded-full bg-green-400" />
      <span className="font-mono text-sm">{address.slice(0,6)}...{address.slice(-4)}</span>
      <BalanceBadge onRefresh={() => getBalances()} />
      <button onClick={disconnect} className="text-xs text-muted-foreground hover:text-destructive">
        Disconnect
      </button>
    </div>
  ) : (
    <button onClick={connect} className="px-4 py-2 bg-primary text-primary-foreground rounded-lg font-medium">
      Connect Wallet
    </button>
  );
}

Contract data with loading skeleton

function TokenBalance({ contractId, address }: { contractId: string; address: string }) {
  const { read } = useContract(contractId);
  const [balance, setBalance] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    setLoading(true);
    read("balance_of", [addressToScVal(address)])
      .then(v => setBalance(v ? scvalToNumber(v).toLocaleString() : "0"))
      .finally(() => setLoading(false));
  }, [contractId, address]);

  if (loading) return <div className="h-6 w-24 bg-muted animate-pulse rounded" />;
  return <span className="font-mono tabular-nums">{balance}</span>;
}

Transaction flow with all 4 phases

function TransferForm({ contractId }: { contractId: string }) {
  const { address, sign } = useWallet();
  const { write, data } = useContract(contractId);
  const [phase, setPhase] = useState<"idle"|"simulating"|"signing"|"submitting"|"confirmed"|"error">("idle");
  const [errorMsg, setErrorMsg] = useState("");

  async function handleTransfer(to: string, amount: bigint) {
    if (!address) return;
    setPhase("simulating");
    try {
      const res = await write(address, "transfer", [
        addressToScVal(address), addressToScVal(to), i128ToScVal(amount),
      ], sign);
      setPhase(res.hash ? "confirmed" : "error");
    } catch (e: any) {
      setErrorMsg(e.message);
      setPhase("error");
    }
  }

  return (
    <div className="space-y-3">
      {/* phase-specific UI */}
      {phase === "simulating" && <p className="text-sm text-muted-foreground animate-pulse">Simulating transfer...</p>}
      {phase === "signing" && <p className="text-sm text-muted-foreground">Check your wallet to approve</p>}
      {phase === "submitting" && <div className="h-1 bg-muted rounded overflow-hidden"><div className="h-full bg-primary w-1/2 animate-slide" /></div>}
      {phase === "confirmed" && <p className="text-sm text-green-500">Transfer confirmed!</p>}
      {phase === "error" && <p className="text-sm text-destructive">{errorMsg}</p>}
      {data.error && <p className="text-xs text-destructive">{data.error}</p>}
    </div>
  );
}

Strict Rules

1. All UI uses Tailwind CSS — no CSS modules, styled-components, or inline styles for layout/color
2. Every dApp supports dark mode via dark: variant — never hardcode colors without a dark counterpart
3. All blockchain queries use useStellarData() — no fetch(), no axios, no raw RPC
4. Read-only uses useContract().read() — simulation, zero fees, no wallet prompt
5. State-changing uses useContract().write() — handles sim + assemble + sign + submit + confirm
6. Every transaction flow phase has a distinct visual state — never show a generic spinner
7. Loading states use skeleton placeholders matching the content shape, not text spinners
8. Error states are context-aware and actionable — not generic "Something went wrong"
9. Wallet connection shows the full lifecycle: disconnected → connecting → connected → disconnecting
10. After write() completion, auto-refresh read() data and balances
11. Never display raw ScVal — convert via helpers from lib/stellar-config.ts
12. Design with intention — pick a bold direction and execute precisely. No generic defaults.