frontend-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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
```

| State | Visual treatment |
|-------|------------------|
| Disconnected | Prominent CTA, subtle pulse animation on the connect button |
| Connecting | Spinner, disabled button, "Opening Freighter..." text |
| Connected | Address badge (abbreviated), XLM balance chip, disconnect affordance |
| Disconnecting | Brief fade before returning to disconnected state |

### Pattern 2 — Transaction Flow

A tx has 4 phases. Each needs distinct UI:

```
Simulate → Sign → Submit → Confirm
```

| Phase | UX |
|-------|----|
| **Simulate** | Show expected state change: "You will send 100 USDC to G..." with gas estimate |
| **Sign** | "Check your wallet to approve" — wallet handles the modal, but show a waiting state |
| **Submit** | Animated progress bar or spinner — "Waiting for ledger confirmation (~5s)" |
| **Confirm** | Success animation + updated balances. Or error with clear reason and retry button |

### 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

| Pattern | Tailwind | When |
|---------|----------|------|
| Address display | `font-mono text-sm truncate max-w-[120px]` | All on-chain addresses |
| Loading skeleton | `animate-pulse bg-muted rounded h-{n} w-{n}` | While contract data loads |
| Balance number | `font-mono tabular-nums` | Numeric on-chain values |
| Status badge | `rounded-full px-2 py-0.5 text-xs font-medium bg-{color}/10 text-{color}` | Tx status, token state |
| Card | `rounded-lg border bg-card text-card-foreground shadow-sm` | Data sections |
| CTA button | `px-4 py-2 bg-primary text-primary-foreground rounded-lg font-medium hover:bg-primary/90` | Primary actions |
| Error message | `text-sm text-destructive bg-destructive/10 rounded px-3 py-2` | Error states |
| Success toast | `text-sm text-emerald-600 bg-emerald-50 dark:text-emerald-400 dark:bg-emerald-950/50` | Confirmation |

### Customizing the dApp Theme

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

```ts
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%" } },
    },

From rylsherdamz-rgb/stellar-forge, MIT.

More from rylsherdamz-rgb/stellar-forge