feat(component): CreditBadge — Balance Status Pill

[bntvllnt]

Summary

Compact, pill-shaped credit balance indicator for persistent display in app headers. Shows formatted currency amount with threshold-based color coding (healthy → low → critical). Supports VIP/unlimited variant. Designed for at-a-glance balance awareness.

Proposed API

<CreditBadge
  balanceCents={2350}
  currency="EUR"
  href="/account/billing"
  thresholds={{ critical: 100, low: 500 }}
/>

<CreditBadge variant="unlimited" href="/account/billing" />

<CreditBadge
  balanceCents={50}
  currency="USD"
  href="/billing"
  thresholds={{ critical: 100, low: 500 }}
/>

Requirements

• Display formatted currency amount (Intl.NumberFormat)
• Threshold-based color: healthy (neutral), low (yellow), critical (red)
• Configurable thresholds via { low: number; critical: number } (in cents)
• unlimited variant: amber pill with "VIP" or custom label
• Optional href — renders as link when provided
• Optional custom icon (defaults to Wallet)
• Tooltip with contextual message per threshold level
• Currency support via locale-aware formatting
• Compact pill layout: icon + formatted amount, rounded-full
• Dark mode: semi-transparent backgrounds with matching border
• Accessible: aria-label describes balance state ("Credit balance: €23.50" / "Balance critically low: €0.50")

Visual States

┌──────────────────────────────────────────────────┐
│  Healthy:   [💰 €23.50]     neutral pill         │
│  Low:       [💰 €4.20]      yellow pill          │
│  Critical:  [💰 €0.50]      red pill             │
│  Unlimited: [💰 VIP]        amber pill           │
└──────────────────────────────────────────────────┘

Use Cases

• SaaS app header showing prepaid credit balance
• API platform showing remaining API credits
• Gaming platform currency display
• Cloud dashboard showing remaining compute credits

Composes

• Badge (base styling)
• Lucide icons (Wallet)

Origin

Extracted from apps/web-ai-os/components/billing/BalanceWidget.tsx in vllnt/vllnt monorepo.