# Token Budget Management Guide

**Purpose:** Help AI estimate generation complexity and decide phasing strategy

---

## 🧮 Token Estimation Formula

### Base Widget Costs

```
Foundation (always required):
- package.json: ~150 tokens
- tsconfig.json: ~80 tokens
- vite.config.ts: ~80 tokens
- index.html (root): ~50 tokens
TOTAL FOUNDATION: ~360 tokens
```

### Per-Entity Costs

For each domain entity (e.g., Transaction, Policy, User):

```
- Type definition: ~150 tokens
- Mock data (20 items): ~600 tokens
- Repository (5 functions): ~500 tokens
- Store slice: ~400 tokens
- Custom hook: ~250 tokens
TOTAL PER ENTITY: ~1,900 tokens
```

### Per-Component Costs

```
Simple component (card, button group): ~300 tokens
Medium component (table, form): ~800 tokens
Complex component (chart, modal with logic): ~1,500 tokens
```

### Supporting Files

```
- i18n files (2 languages): ~200 tokens
- Utils (errorHandler, formatters): ~150 tokens
- Config files (widgetConfig, i18nConfig): ~150 tokens
- README.md: ~200 tokens
TOTAL SUPPORTING: ~700 tokens
```

---

## 📊 Complexity Assessment

### Example: Banking Dashboard

**User prompt:**
```
Banking dashboard with balance, transactions table,
spending charts, filters, and alerts
```

**Analysis:**

```
Foundation: 360 tokens

Entities:
- Transaction: 1,900 tokens
- Balance: 1,900 tokens
SUBTOTAL: 3,800 tokens

Components:
- BalanceCard (simple): 300 tokens
- TransactionTable (medium): 800 tokens
- SpendingPieChart (complex): 1,500 tokens
- SpendingLineChart (complex): 1,500 tokens
- FilterBar (medium): 800 tokens
- AlertBanner (simple): 300 tokens
SUBTOTAL: 5,200 tokens

Supporting: 700 tokens

TOTAL: 360 + 3,800 + 5,200 + 700 = 10,060 tokens

CONCLUSION: COMPLEX - Requires 3 phases
```

**Phasing Strategy:**

```
Phase 1 (MVP - 3,860 tokens):
- Foundation: 360
- Entities: 3,800
- Components: BalanceCard (300) + TransactionTable (800)
- Supporting: 600
RESULT: Functional widget with balance + transactions

Phase 2 (3,800 tokens):
- Components: SpendingPieChart (1,500) + SpendingLineChart (1,500)
- Enhanced mock data: 600
- Additional supporting: 200
RESULT: Add analytics visualizations

Phase 3 (2,400 tokens):
- Components: FilterBar (800) + AlertBanner (300)
- Filter logic: 800
- Alert logic: 500
RESULT: Complete widget with all features
```

---

## 🎯 Decision Tree

```
START: Receive user prompt
  │
  ├─> Count features mentioned
  │   │
  │   ├─> 1-3 features
  │   │   └─> Estimate: ~4,000 tokens
  │   │       └─> Strategy: Single phase
  │   │
  │   ├─> 4-5 features
  │   │   └─> Estimate: ~6,000-8,000 tokens
  │   │       └─> Strategy: 2 phases (MVP + Full)
  │   │
  │   └─> 6+ features
  │       └─> Estimate: ~10,000+ tokens
  │           └─> Strategy: 3+ phases
  │
  └─> Check for complexity signals:
      - "comprehensive", "complete", "full"
      - Multiple data sources
      - Charts/visualizations
      - Advanced filters
      - Export/import functionality

      If ANY present:
      └─> Add 1 phase to strategy
```

---

## 📝 Templates for Token Assessment

### Assessment Message Template

When prompt seems complex:

```
"I've analyzed your request and estimated ~[X],000 tokens needed.

This is a [SIMPLE/MEDIUM/COMPLEX] widget.

Recommended strategy:
Phase 1 (MVP): [List core features] (~[Y]K tokens)
  → Result: Fully functional widget with essentials

[If medium/complex:]
Phase 2: [List enhancements] (~[Y]K tokens)
  → Result: Enhanced widget with [features]

[If complex:]
Phase 3: [List advanced features] (~[Y]K tokens)
  → Result: Complete widget with all features

I'll start with Phase 1. Proceed?"
```

### Quick Estimates

```
Very Simple Widget (blog card, simple form):
~2,500 tokens → Single phase

Simple Widget (dashboard with 2-3 cards):
~4,000 tokens → Single phase

Medium Widget (table + filters + modal):
~6,500 tokens → 2 phases

Complex Widget (full dashboard with charts):
~10,000 tokens → 3 phases

Very Complex Widget (multi-page app):
~15,000+ tokens → 4+ phases OR suggest simplification
```

---

## ⚠️ Warning Signs

If you see these in a prompt, it's DEFINITELY complex:

- "comprehensive"
- "complete solution"
- "full featured"
- "with everything"
- Lists 7+ features
- Mentions "and more"
- "all the bells and whistles"

**Action:** Automatically propose phasing, don't wait to hit token limit.

---

## ✅ Best Practices

1. **Estimate BEFORE starting generation**
   - Read entire prompt
   - Count entities and components
   - Calculate rough token total

2. **Communicate early**
   - If complex, tell user upfront
   - Propose phasing strategy
   - Get approval before generating

3. **Be conservative**
   - If estimate is close to limit, phase it
   - Better to under-promise and over-deliver

4. **Use templates aggressively**
   - Templates save ~40% tokens
   - Always start from the canonical `dynamic-react-vite-base-template`
   - Copy patterns instead of generating from scratch

5. **Monitor as you generate**
   - Keep mental count of tokens used
   - If approaching limit, stop and communicate
   - Don't generate partial non-functional widget

---

**Remember:** Your goal is functional code every time, not maximum features.