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
```tsx
<ChatInput
  // ... other props
  showTokenUsage={true}
/>
```

### Conditional Display
```tsx
<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:

```tsx
// 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