suna/frontend/TOKEN_USAGE_UX_IMPLEMENTATION.md

Enhanced Token Usage UX/UI Implementation

Overview

This implementation provides a beautiful, modern token usage display for Suna's chat input interface that shows users their current token usage with an expand/collapse feature, as requested in the Slack thread.

Features Implemented

🎯 Core Features

1. Compact Display: Shows remaining balance in format "$X.XX left" with status indicator
2. Expand/Collapse: Click to expand for detailed usage statistics
3. Smart Color Coding:
   • Green/muted for normal usage
   • Amber for 80%+ usage (near limit)
   • Red for reached limit
4. Upgrade Integration: Direct "Upgrade" button that opens billing modal
5. Configurable: Can be enabled/disabled via showTokenUsage prop

🎨 Visual Design

• Modern Design: Glassmorphic background with backdrop blur
• Smooth Animations: Transitions for expand/collapse and color changes
• Progress Bar: Visual representation of usage percentage
• Status Indicators: Icons and badges for plan type and usage status
• Mobile Friendly: Responsive design that works on all screen sizes

📊 Data Display

• Current Usage: Shows used amount vs. total limit
• Remaining Balance: Prominently displays money left
• Usage Percentage: Visual progress bar with percentage
• Plan Information: Shows current plan name (Free, Pro, etc.)
• Warning States: Special UI for near-limit and at-limit scenarios

Implementation Details

New Component: TokenUsageDisplay

Located at: frontend/src/components/thread/chat-input/token-usage-display.tsx

Key Props:

• subscriptionData: Current subscription information from API
• onUpgradeClick: Callback to open billing modal
• showUsageDisplay: Boolean to control visibility
• className: Optional styling override

Features:

• Automatically hides in local development mode
• Only displays for users with usage limits (free tier or paid plans with limits)
• Responsive design with different layouts for mobile/desktop
• Accessible with keyboard navigation support

Integration Points

Modified Components:

1. MessageInput (message-input.tsx)

   • Added showTokenUsage prop
   • Integrated TokenUsageDisplay component
   • Conditionally hides old upgrade text when new display is active
   • Uses subscription data from React Query

2. ChatInput (chat-input.tsx)

   • Added showTokenUsage prop passthrough
   • Maintains backward compatibility

3. Thread Page ([threadId]/page.tsx)

   • Enabled token usage display with showTokenUsage={true}

4. Dashboard (dashboard-content.tsx)

   • Enabled token usage display for main chat interface

Data Integration

Subscription Data Source:

• Uses useSubscription() hook from React Query
• Fetches real-time usage data from /billing/subscription endpoint
• Automatically updates when usage changes

Key Data Points:

• current_usage: Amount spent this month (in dollars)
• cost_limit: Monthly spending limit (in dollars)
• status: Subscription status ('no_subscription', 'active', etc.)
• plan_name: Display name for current plan

Usage Examples

Basic Implementation

<ChatInput
  // ... other props
  showTokenUsage={true}
/>

Conditional Display

<ChatInput
  // ... other props
  showTokenUsage={userTier === 'free' || showUsageForPaidUsers}
/>

Benefits Over Previous Implementation

🆚 Before vs After

Before:

• Simple text: "Upgrade for more usage"
• No usage information displayed
• Only shown for free tier
• Static, non-interactive

After:

• Dynamic usage display: "$X.XX left"
• Detailed breakdown when expanded
• Works for all subscription tiers
• Interactive with smooth animations
• Better visual hierarchy

🎯 UX Improvements

1. Information at a Glance: Users immediately see their remaining balance
2. Progressive Disclosure: Detailed info available on demand via expand
3. Visual Feedback: Color coding provides instant status understanding
4. Clear Call-to-Action: Prominent upgrade button when needed
5. Non-Intrusive: Compact by default, doesn't interfere with chat

Configuration Options

The component can be customized for different contexts:

// Always show (recommended for main chat interfaces)
showTokenUsage={true}

// Conditional based on subscription
showTokenUsage={subscriptionData?.status === 'no_subscription'}

// Disabled for specific contexts (agent testing, etc.)
showTokenUsage={false}

Technical Implementation Notes

Performance Considerations

• Uses React Query for efficient data fetching and caching
• Minimal re-renders with proper dependency management
• Lightweight component with optimized animations

Accessibility

• Proper ARIA labels for screen readers
• Keyboard navigation support
• High contrast color scheme
• Semantic HTML structure

Browser Compatibility

• Modern CSS features with fallbacks
• Responsive design patterns
• Cross-browser tested animations

Future Enhancements

Potential improvements that could be added:

1. Usage Trends: Historical usage graph in expanded view
2. Notifications: Toast alerts when approaching limits
3. Customizable Thresholds: User-defined warning levels
4. Usage Breakdown: Per-model or per-project usage details
5. Predictive Insights: Estimated time until limit reached

Conclusion

This implementation successfully addresses the Slack request for improved UX/UI around token usage display. It provides users with clear, actionable information about their usage while maintaining a clean, modern interface that enhances rather than clutters the chat experience.

The solution is:

• ✅ Configurable - Can be enabled/disabled as needed
• ✅ Beautiful - Modern design with smooth interactions
• ✅ Functional - Shows real usage data with upgrade path
• ✅ Scalable - Works across different subscription tiers
• ✅ Accessible - Follows best practices for all users