feat(billing): segment the usage bar into included vs spend-limit portions

adboio · adboio · commit 82b3e9ce48c1 · 2026-07-16T10:13:05.000-04:00
The 1px notch marking where the included allowance ends was barely
visible in either theme. Replace it with a physically segmented bar:
the $20 included allowance and the org spend limit render as separate
gap-divided segments, usage fills the included segment green before
pouring into the accent spend-limit segment, and a dot legend names
each amount. Exceeded turns both segments and dots red; a $0 spend
limit collapses to the included segment alone; the free tier keeps the
plain single-track bar.

Generated-By: PostHog Code
Task-Id: b24f71e2-3751-4a6b-b5d8-a24147c4c067
diff --git a/packages/core/src/billing/usageDisplay.ts b/packages/core/src/billing/usageDisplay.ts
@@ -1,14 +1,5 @@
 import type { UsageBucket, UsageOutput } from "../usage/schemas";
 
-/**
- * The monthly usage allowance included for every org under Code usage
- * billing — the "first $20 each month is included" from the billing product
- * config. The gateway has no field for it: a subscribed org's
- * `ai_credits.limit_usd` arrives as one merged number (allowance + configured
- * spend limit), so display code peels the allowance back off with this
- * constant. If billing ever changes the allowance or starts sending a
- * breakdown, this constant (and the copy quoting $20) is the seam.
- */
 export const CODE_INCLUDED_USAGE_USD = 20;
 
 /** Confirmed free tier only — an absent `code_usage_subscribed` is unknown, never free. */
@@ -18,14 +9,6 @@ export function isCodeUsageFreeTier(
   return usage?.code_usage_subscribed === false;
 }
 
-/**
- * The spend limit the org actually configured in billing settings ($50 by
- * default), recovered from the merged `limit_usd`. Null when it can't be
- * recovered: unconfirmed/free orgs (their limit IS the allowance), missing
- * numbers, or a merged limit below the allowance. Zero is a real answer — a
- * subscribed org whose merged limit equals the allowance set its spend limit
- * to $0.
- */
 export function codeOrgSpendLimitUsd(
   usage:
     | Pick<UsageOutput, "code_usage_subscribed" | "ai_credits">
@@ -35,7 +18,6 @@ export function codeOrgSpendLimitUsd(
   if (usage?.code_usage_subscribed !== true) return null;
   const limitUsd = usage.ai_credits?.limit_usd;
   if (limitUsd == null || limitUsd < CODE_INCLUDED_USAGE_USD) return null;
-  // Round away float dust — the wire amounts are already cent-rounded.
   return Math.round((limitUsd - CODE_INCLUDED_USAGE_USD) * 100) / 100;
 }
 
@@ -52,9 +34,6 @@ export type CodeUsageMeter =
       percent: number;
       exceeded: boolean;
       resetAt: string;
-      // How the merged limit decomposes for a subscribed org, so the meter
-      // can explain "$70" as $20 included + $50 spend limit. Null when the
-      // split is unknown (free tier, or a limit below the allowance).
       breakdown: CodeUsageBreakdown | null;
     }
   | { kind: "bucket"; bucket: UsageBucket }
@@ -97,7 +76,6 @@ export function formatUsdAmount(amount: number): string {
   return Number.isInteger(amount) ? `$${amount}` : `$${amount.toFixed(2)}`;
 }
 
-/** One shared phrasing for the merged-limit explanation, e.g. "$20 included + $50 org spend limit". */
 export function formatUsageBreakdown(breakdown: CodeUsageBreakdown): string {
   return `${formatUsdAmount(breakdown.includedUsd)} included + ${formatUsdAmount(breakdown.spendLimitUsd)} org spend limit`;
 }
diff --git a/packages/ui/src/features/billing/UsageBillingAnnouncementModal.tsx b/packages/ui/src/features/billing/UsageBillingAnnouncementModal.tsx
@@ -25,10 +25,6 @@ export function UsageBillingAnnouncementModal() {
   const cloudRegion = useAuthStateValue((state) => state.cloudRegion);
   const { usage } = useUsage({ enabled: isOpen });
 
-  // A subscribed org's limit_usd merges the included $20 with the configured
-  // spend limit — quote the recovered spend limit, the number the org set.
-  // Free orgs (whose limit_usd is just the first bullet's $20) get the
-  // default-limit line instead.
   const spendLimitUsd = codeOrgSpendLimitUsd(usage);
 
   useEffect(() => {
diff --git a/packages/ui/src/features/billing/UsageButton.tsx b/packages/ui/src/features/billing/UsageButton.tsx
@@ -71,9 +71,6 @@ export function UsageButton() {
   const resetLabel = formatResetTime(
     meter.kind === "dollars" ? meter.resetAt : meter.bucket.reset_at,
   );
-  // The subscribed meter's limit is a merged number (included allowance +
-  // configured spend limit); without the split, "$70" matches nothing the
-  // user ever set.
   const breakdownLabel =
     meter.kind === "dollars" && meter.breakdown
       ? formatUsageBreakdown(meter.breakdown)
diff --git a/packages/ui/src/features/billing/UsageMeter.stories.tsx b/packages/ui/src/features/billing/UsageMeter.stories.tsx
@@ -16,29 +16,46 @@ const meta: Meta<typeof UsageMeter> = {
 export default meta;
 type Story = StoryObj<typeof UsageMeter>;
 
-// A subscribed org on default settings: the $70 limit is $20 included
-// allowance + the $50 default spend limit, spelled out in the detail line
-// with the notch marking where the included allowance ends.
+// A subscribed org on default settings: the $70 limit renders as two
+// segments — the $20 included allowance (green) and the $50 default spend
+// limit (accent) — with a dot legend naming each amount. Usage still inside
+// the included allowance only fills the green segment.
 export const SubscribedWithBreakdown: Story = {
   args: {
     label: "Usage this period",
     percent: 18,
     valueLabel: "$12.40 of $70",
-    detail: "$20 included + $50 org spend limit. Resets Jul 31 at 2:00 PM PDT",
-    markerPercent: (20 / 70) * 100,
+    detail: "Resets Jul 31 at 2:00 PM PDT",
+    breakdown: { includedUsd: 20, spendLimitUsd: 50, usedUsd: 12.4 },
   },
 };
 
+// Past the allowance: the green segment is full and billable usage fills the
+// accent segment.
 export const SubscribedPastIncluded: Story = {
   args: {
     label: "Usage this period",
     percent: 66,
     valueLabel: "$46.20 of $70",
-    detail: "$20 included + $50 org spend limit. Resets Jul 31 at 2:00 PM PDT",
-    markerPercent: (20 / 70) * 100,
+    detail: "Resets Jul 31 at 2:00 PM PDT",
+    breakdown: { includedUsd: 20, spendLimitUsd: 50, usedUsd: 46.2 },
+  },
+};
+
+// A subscribed org that set its spend limit to $0: only the included segment
+// (and its legend entry) renders.
+export const ZeroSpendLimit: Story = {
+  args: {
+    label: "Usage this period",
+    percent: 65,
+    valueLabel: "$13 of $20",
+    detail: "Resets Jul 31 at 2:00 PM PDT",
+    breakdown: { includedUsd: 20, spendLimitUsd: 0, usedUsd: 13 },
   },
 };
 
+// Free tier has no breakdown — its limit IS the allowance, so the plain
+// single-track bar renders.
 export const FreeTier: Story = {
   args: {
     label: "Monthly free usage",
@@ -53,9 +70,8 @@ export const Exceeded: Story = {
     label: "Usage this period",
     percent: 100,
     valueLabel: "$70 of $70",
-    detail:
-      "Limit exceeded. $20 included + $50 org spend limit. Resets Jul 31 at 2:00 PM PDT",
-    markerPercent: (20 / 70) * 100,
+    detail: "Limit exceeded. Resets Jul 31 at 2:00 PM PDT",
+    breakdown: { includedUsd: 20, spendLimitUsd: 50, usedUsd: 70 },
     color: "red",
   },
 };
diff --git a/packages/ui/src/features/billing/UsageMeter.tsx b/packages/ui/src/features/billing/UsageMeter.tsx
@@ -1,27 +1,34 @@
+import { formatUsdAmount } from "@posthog/core/billing/usageDisplay";
+import { cn } from "@posthog/quill";
 import { Flex, Progress, Text } from "@radix-ui/themes";
 
+interface UsageMeterBreakdown {
+  includedUsd: number;
+  spendLimitUsd: number;
+  usedUsd: number;
+}
+
 interface UsageMeterProps {
   label: string;
   percent: number;
   valueLabel: string;
   detail: string;
   color?: "red";
-  // Where a boundary inside the limit falls (e.g. the end of the included
-  // allowance), as a percent of the bar. Rendered as a notch over the track.
-  markerPercent?: number;
+  breakdown?: UsageMeterBreakdown;
 }
 
+const clampPercent = (value: number): number =>
+  Math.min(100, Math.max(0, value));
+
 export function UsageMeter({
   label,
   percent,
   valueLabel,
   detail,
   color,
-  markerPercent,
+  breakdown,
 }: UsageMeterProps) {
   const borderColor = color === "red" ? "var(--red-7)" : "var(--gray-5)";
-  const showMarker =
-    markerPercent != null && markerPercent > 0 && markerPercent < 100;
 
   return (
     <Flex
@@ -37,21 +44,94 @@ export function UsageMeter({
         <Text className="font-medium text-sm">{label}</Text>
         <Text className="font-medium text-sm">{valueLabel}</Text>
       </Flex>
-      <div className="relative">
+      {breakdown ? (
+        <SegmentedUsageBar
+          percent={percent}
+          breakdown={breakdown}
+          exceeded={color === "red"}
+        />
+      ) : (
         <Progress
           value={percent}
           size="2"
           color={color === "red" ? "red" : undefined}
         />
-        {showMarker && (
+      )}
+      <Text className="text-(--gray-9) text-[13px]">{detail}</Text>
+    </Flex>
+  );
+}
+
+function SegmentedUsageBar({
+  percent,
+  breakdown,
+  exceeded,
+}: {
+  percent: number;
+  breakdown: UsageMeterBreakdown;
+  exceeded: boolean;
+}) {
+  const { includedUsd, spendLimitUsd, usedUsd } = breakdown;
+  const totalUsd = includedUsd + spendLimitUsd;
+  const hasPaidSegment = spendLimitUsd > 0 && totalUsd > 0;
+  const includedFill =
+    includedUsd > 0 ? clampPercent((usedUsd / includedUsd) * 100) : 100;
+  const paidFill = hasPaidSegment
+    ? clampPercent(((usedUsd - includedUsd) / spendLimitUsd) * 100)
+    : 0;
+  const includedDot = exceeded ? "bg-(--red-9)" : "bg-(--green-9)";
+  const paidDot = exceeded ? "bg-(--red-9)" : "bg-(--accent-9)";
+
+  return (
+    <Flex direction="column" gap="2">
+      <div
+        role="progressbar"
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-valuenow={Math.round(clampPercent(percent))}
+        className="flex h-2 w-full gap-[3px]"
+      >
+        <div
+          className="h-full overflow-hidden rounded-full bg-(--gray-a3)"
+          style={{
+            width: hasPaidSegment
+              ? `${(includedUsd / totalUsd) * 100}%`
+              : "100%",
+          }}
+        >
           <div
-            aria-hidden
-            className="absolute inset-y-0 w-px bg-(--gray-1)"
-            style={{ left: `${markerPercent}%` }}
+            className={cn(
+              "h-full transition-[width] duration-300",
+              includedDot,
+            )}
+            style={{ width: `${includedFill}%` }}
           />
+        </div>
+        {hasPaidSegment && (
+          <div className="h-full flex-1 overflow-hidden rounded-full bg-(--gray-a3)">
+            <div
+              className={cn("h-full transition-[width] duration-300", paidDot)}
+              style={{ width: `${paidFill}%` }}
+            />
+          </div>
         )}
       </div>
-      <Text className="text-(--gray-9) text-[13px]">{detail}</Text>
+      <Flex align="center" gap="4" wrap="wrap">
+        <Flex align="center" gap="2">
+          <span className={cn("size-2 rounded-full", includedDot)} />
+          <Text className="text-(--gray-9) text-[13px]">
+            {formatUsdAmount(includedUsd)} included
+          </Text>
+        </Flex>
+        {hasPaidSegment && (
+          <Flex align="center" gap="2">
+            <span className={cn("size-2 rounded-full", paidDot)} />
+            <Text className="text-(--gray-9) text-[13px]">
+              {formatUsdAmount(spendLimitUsd)} org spend limit
+            </Text>
+          </Flex>
+        )}
+      </Flex>
     </Flex>
   );
 }
diff --git a/packages/ui/src/features/settings/sections/PlanUsageSettings.tsx b/packages/ui/src/features/settings/sections/PlanUsageSettings.tsx
@@ -6,7 +6,6 @@ import {
 import {
   codeUsageMeter,
   formatResetTime,
-  formatUsageBreakdown,
   formatUsdAmount,
   isCodeUsageFreeTier,
 } from "@posthog/core/billing/usageDisplay";
@@ -179,20 +178,10 @@ export function PlanUsageSettings() {
                 label={freeTier ? "Monthly free usage" : "Usage this period"}
                 percent={meter.percent}
                 valueLabel={`${formatUsdAmount(meter.usedUsd)} of ${formatUsdAmount(meter.limitUsd)}${freeTier ? " included" : ""}`}
-                detail={[
-                  meter.exceeded ? "Limit exceeded." : null,
-                  // Spell out how the merged limit is composed — "$70" on its
-                  // own reads as a mystery number to an org that set $50.
+                detail={`${meter.exceeded ? "Limit exceeded. " : ""}${formatResetTime(meter.resetAt)}`}
+                breakdown={
                   meter.breakdown
-                    ? `${formatUsageBreakdown(meter.breakdown)}.`
-                    : null,
-                  formatResetTime(meter.resetAt),
-                ]
-                  .filter(Boolean)
-                  .join(" ")}
-                markerPercent={
-                  meter.breakdown
-                    ? (meter.breakdown.includedUsd / meter.limitUsd) * 100
+                    ? { ...meter.breakdown, usedUsd: meter.usedUsd }
                     : undefined
                 }
                 color={meter.exceeded ? "red" : undefined}
