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

adboio · web-flow · commit c8d104e85b2d · 2026-07-16T09:57:10.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/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,37 @@
+import { formatUsdAmount } from "@posthog/core/billing/usageDisplay";
+import { cn } from "@posthog/quill";
 import { Flex, Progress, Text } from "@radix-ui/themes";
 
+// How the merged limit splits for the segmented bar: the included allowance
+// and the configured spend limit render as physically separate segments so a
+// "$70" total is visibly $20 + $50, with usage drawn across both.
+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 +47,101 @@ 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>
+  );
+}
+
+/**
+ * Two-segment usage bar: the included allowance fills green, the org spend
+ * limit fills accent, split by a gap sized to each side's share of the merged
+ * limit. Usage pours through the included segment first — matching how
+ * billing spends the allowance before billable credits — and a dot legend
+ * names each segment's amount. Exceeded turns both fills (and dots) red.
+ */
+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,13 @@ 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)}`}
+                // Splits the bar so "$70" is visibly $20 included + $50 spend
+                // limit — a merged total reads as a mystery number to an org
+                // that set $50.
+                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}
