# Frontend Design

> >

- **Type:** Skill
- **Install:** `agentstack add skill-rylsherdamz-rgb-stellar-forge-frontend-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rylsherdamz-rgb](https://agentstack.voostack.com/s/rylsherdamz-rgb)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rylsherdamz-rgb](https://github.com/rylsherdamz-rgb)
- **Source:** https://github.com/rylsherdamz-rgb/stellar-forge/tree/master/skills/frontend-design
- **Website:** https://www.npmjs.com/package/create-stellar-agentic

## Install

```sh
agentstack add skill-rylsherdamz-rgb-stellar-forge-frontend-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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%" } },
    },
    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:

```tsx

```

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

| UI Concern | Hook | Purpose |
|------------|------|---------|
| Wallet button | `useWallet()` | Connect/disconnect, address, sign |
| Balance list | `useStellarData().getBalances` | All asset balances |
| Contract reader | `useContract(id).read()` | Simulation-only read |
| Contract writer | `useContract(id).write()` | Sign + submit + confirm |
| Event stream | `useStellarData().getEvents` | On-chain event display |
| Transaction status | `useStellarData().getTransaction` | Confirmation check |

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

| File | Location | Contents |
|------|----------|----------|
| Provider | `templates/frontend/providers/wallet-provider.tsx` | React context + `useWallet()` export |
| Hook source | `templates/frontend/hooks/use-stellar-data.ts` | `getBalances`, `queryContract`, `getContractData`, `getEvents` |
| Hook source | `templates/frontend/hooks/use-contract.ts` | `read()` (simulation), `write()` (sign+submit+confirm) |
| Hook source | `templates/frontend/hooks/use-stellar-wallet.ts` | `connect`, `disconnect`, `sign`, `getBalances` |
| Component | `templates/frontend/components/connect-button.tsx` | Connect + disconnect + XLM badge |
| Component | `templates/frontend/components/invoke-contract.tsx` | Read/write any contract method from UI |
| Component | `templates/frontend/components/send-payment.tsx` | Send XLM with balance refresh |
| Config | `templates/frontend/lib/stellar-config.ts` | RPC config, network config, ScVal helpers |
| Examples | `templates/frontend/examples/use-stellar-data-example.tsx` | BalanceViewer, ContractReader, EventList, UsdcBalance |
| Examples | `templates/frontend/examples/dashboard-page.tsx` | Full dashboard layout with ConnectButton + InvokeContract |
| Deploy tracker | `data/deployments/.json` | Contract IDs + WASM hashes per network |
| Deploy script | `scripts/deploy-contract.sh` | Build → test gate → deploy → record → .env update |
| Env template | `.env.example` | All env vars with contract address placeholders |

## Working Examples

### Wallet connect with balance badge

```tsx
function StellarStatusBar() {
  const { address, connect, disconnect, getBalances } = useWallet();
  return address ? (
    
      
      {address.slice(0,6)}...{address.slice(-4)}
       getBalances()} />
      
        Disconnect
      
    
  ) : (
    
      Connect Wallet
    
  );
}
```

### Contract data with loading skeleton

```tsx
function TokenBalance({ contractId, address }: { contractId: string; address: string }) {
  const { read } = useContract(contractId);
  const [balance, setBalance] = useState(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 ;
  return {balance};
}
```

### Transaction flow with all 4 phases

```tsx
function TransferForm({ contractId }: { contractId: string }) {
  const { address, sign } = useWallet();
  const { write, data } = useContract(contractId);
  const [phase, setPhase] = useState("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 (
    
      {/* phase-specific UI */}
      {phase === "simulating" && Simulating transfer...}
      {phase === "signing" && Check your wallet to approve}
      {phase === "submitting" && }
      {phase === "confirmed" && Transfer confirmed!}
      {phase === "error" && {errorMsg}}
      {data.error && {data.error}}
    
  );
}
```

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rylsherdamz-rgb](https://github.com/rylsherdamz-rgb)
- **Source:** [rylsherdamz-rgb/stellar-forge](https://github.com/rylsherdamz-rgb/stellar-forge)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/create-stellar-agentic

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-rylsherdamz-rgb-stellar-forge-frontend-design
- Seller: https://agentstack.voostack.com/s/rylsherdamz-rgb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.