Design exploration: AI credit usage, limits, and purchase flows

[shaunandrews]

Related issues

None yet — this PR is the design artifact. If the direction is accepted, follow-up implementation issues should define the production data source, billing integration, rollout, and final copy.

How AI was used in this PR

AI was used to implement and iterate on the prototype during a live design-review loop. The resulting interfaces were manually reviewed in both light and dark themes, and the state logic is covered by focused tests.

Executive summary

Important

This is a design exploration, not a merge recommendation. It is intentionally broader and more prototype-oriented than production code should be. The goal is to make the pricing, usage, limit, lockout, and purchase states tangible enough to evaluate together.

Individual pieces are deliberately easy to cherry-pick or reimplement. If the team decides the whole direction is close enough to productionize and ship, that would be great too—but this PR should not be treated as ready to ship in its current form.

This exploration asks how Studio’s agentic UI should communicate AI credit consumption before, during, and after a user reaches their allowance. It covers the settings surface, persistent sidebar messaging, an in-composer warning, hard lockout states, a simulated credit-purchase handoff, and purchase confirmation.

Proposed Changes

• Make the Usage settings tab a simpler, meter-led summary of monthly allowance, extra AI credits, and preview-site usage.
• Represent monthly allowance and purchased credits as separate pools, including the case where credits are purchased before the monthly allowance is exhausted.
• Surface persistent usage messages in the sidebar at 80% and 90%.
• Attach a compact, yellow-tinted warning strip to the composer at 90%.
• Replace the composer with a purchase-focused message when no credits remain, with distinct monthly-allowance and purchased-credit copy.
• Keep adding credits available from settings, warnings, and lockout states.
• Compare three one-time purchase selectors: fixed cards, presets plus a custom amount, and a range slider with an editable value.
• Prototype a simulated handoff to WordPress.com checkout.
• Confirm a simulated purchase with a success toast.
• Include explicit prototype controls for reviewing every usage state and purchase variant.

Review guide

The most valuable review is on the product and interaction decisions:

1. Information hierarchy: Is the simplified Usage panel enough, and are monthly allowance and extra credits understandable as separate pools?
2. Threshold behavior: Is a sidebar message at 80% plus an attached composer strip at 90% the right escalation?
3. Lockout behavior: Should chat and New chat be unavailable when all credit pools are exhausted?
4. Copy: Do the monthly and extra-credit exhaustion messages explain the next step without feeling like errors?
5. Purchase trust: Does the modal clearly set the expectation that checkout happens on WordPress.com?
6. Purchase amount selection: Which selector best balances speed, flexibility, and clarity that one credit equals one dollar?
7. Message system: Sidebar messages currently carry semantic intent, but the shared card presentation remains visually neutral. Is that desirable, or should warning/success intent become visible there?

Okay to skim

• The local prototype scenario store and state-switching controls.
• Screenshot binaries under docs/design-explorations/usage-interfaces/.
• The simulated purchase mutation; it exists only to make the end-to-end interaction reviewable.

Screenshots

Purchase UI variants

These are intentionally competing directions presented together for design review, not three interfaces intended to ship.

Fixed cards	Presets + custom amount	Editable slider

Core journey

Usage approaching the limit	Warning attached to the composer

Monthly allowance exhausted	Extra credits exhausted

Purchase handoff	Purchase confirmation

Complete 17-state gallery

Monthly allowance states

36%	80%	90%	100%

Extra-credit states

In reserve	36%	80%	90%	100%

Chat states

Monthly 80%	Monthly 90%

Extra credits 80%	Extra credits 90%

Monthly lockout	Extra-credit lockout

Purchase flow

Add credits	Credits added

Known tradeoffs and follow-ups

• Usage values, the $50 allowance, and the Sep 3 reset date are prototype data.
• The purchase flow does not open WordPress.com or process a payment; it simulates checkout and locally adds credits.
• The scenario and purchase-variant switchers are intentionally exposed for design review and should not ship.
• There is no production limits/billing API integration, persistence contract, analytics plan, or rollout strategy.
• Final production copy needs dynamic dates, currency handling, localization review, and confirmation from the pricing workstream.
• Before shipping, decide whether existing sidebar message intents should remain visually neutral or gain warning/success color and icon treatments.
• Productionization should likely cherry-pick or reimplement the accepted pieces behind real account data rather than merge this prototype wholesale.

Safety checklist

• Feature flag or production gating — not included; required before any ship path.
• No data migrations.
• No production billing or payment API calls.
• No security- or privacy-sensitive data added.
• Existing non-prototype chat behavior remains covered by focused tests.
• Manually verified in light and dark themes.
• Rollback is straightforward: do not merge, or revert the exploration commits.

Testing Instructions

1. Build the Agentic UI:

   npm run cli:build:ui
   node apps/cli/dist/cli/main.mjs ui --no-open

2. Open http://localhost:8081/settings?tab=usage.
3. Use the prototype controls to review monthly allowance and extra-credit states.
4. Open a chat and verify:
   • 80%: sidebar message only.
   • 90%: sidebar message plus attached composer strip.
   • 100% monthly: monthly reset lockout copy.
   • 100% extra: purchased-credit lockout copy.
5. Use Add credits from settings, the sidebar, the strip, and lockout.
6. Switch among Cards, Presets + custom, and Slider using the purchase control above the scrim.
7. In Slider, enter an amount above $200 and verify the off-the-chart state; typed values cap at $99,999.
8. Continue through the modal and verify the Credits added success toast.
9. Repeat key states in light and dark themes.

Validation completed:

• npx eslint --fix on all modified TypeScript files
• npm run typecheck
• npm test -- apps/ui/src/components/settings-view/usage-panel.test.tsx apps/ui/src/data/queries/use-app-messages.test.tsx apps/ui/src/ui-classic/components/session-view/index.test.tsx apps/ui/src/ui-classic/components/session-view/session-chat-actions.test.tsx — 39 tests passed
• npm run cli:build:ui
• Manual light/dark verification

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?
• Production data and billing integration defined.
• Prototype controls removed or gated.
• Final product/copy review completed.
• Team explicitly decides which parts, if any, should ship.