CodexBar · Implementation Handoff

LLM Usage Burn-Down Widget

A medium macOS widget (~360×170pt) that plots remaining usage budget against an ideal steady-burn line — the agile-sprint burn-down, applied to a 5-hour or 7-day LLM limit. This doc captures the model, the exact contrast rules, and the two rendering modes the widget must support.

1 · How the chart reads

Y axis = budget remaining, 100 → 0. X axis = the usage window (start → reset). A point above the ideal line means you're conserving; below means you're burning too fast.

Actual — budget remaining

The hero line. Real consumption so far. 2.4px solid, gradient fill beneath (hue → transparent, ~30% top). Highest-contrast object on the chart.

Ideal — steady rate

Straight 100% → 0% across the window: the pace that lands exactly at reset. A reference, not data — 1.4px dashed, knocked-back to ~50% luminance so it recedes.

Projection — run-out

Extends the recent burn rate to 0%. Fine dotted (0.5/3.5) so it never reads as real data. If it crosses 0 inside the window, the user runs dry before reset.

Now

Vertical hairline + a node at the current value, ringed in the background color so it punches off whatever it overlaps. The brightest point on the chart.

2 · Two rendering modes — the critical requirement

macOS renders desktop widgets in full color, but the moment an app is foregrounded the system desaturates them into a vibrant monochrome material. The widget must be fully legible in both — this is where the previous build broke.

Full color · desktop focused

Pace drives the accent color (see §4). Translucent solid material, gradient background, brand dot in the LLM's hue.

Monochrome · app foregrounded

System strips all hue. Single ink color (white on dark, black on light) over a blurred vibrant material. Pace is carried by geometry + labels only.

The rule that matters: never let hue be the only signal. In monochrome mode green/red/blue are gone, so the actual-vs-ideal relationship, the projection crossing, and the text labels (▼ over pace, Runs out in ~1h 10m) must carry the full story on their own. Validate every layer at ≥3:1 contrast against the material in both appearance modes — the dark + monochrome combination is the one that failed before.

3 · Contrast playbook

The six rules that keep all four layers separable, including single-ink monochrome mode.

Separate by three axes, never hue alone. Stroke weight + dash pattern + luminance differentiate every layer, so the design survives total desaturation.
Ideal = hairline, dashed, ~50% L. 1.4px, 2.5/3 dash, knocked-back lightness. It must recede behind the actual line.
Actual = 2.4px solid + gradient fill. The fill reads even when the stroke is thin on Retina; it is always the dominant object.
Projection = fine dotted. 0.5/3.5 so it never competes with real data. It is the one element allowed a red cue in monochrome mode when over pace.
Now node ringed in the background color. A 2px ring of the material color punches the dot off any line it overlaps.
Re-validate per mode. Recompute accent/ink vs. material contrast for dark-color, light-color, dark-mono, light-mono independently. Don't assume one passing combo covers the rest.

4 · Color semantics & brand identity

In full-color mode the accent (actual line, hero number, pace badge) is driven entirely by pace:

Conserving — under pace (margin > +4%) On pace (±4%) Over pace — burning too fast (margin < −4%)

Brand identity is a single dot next to the LLM name in the upper-left, always in the model's hue (Claude clay, Codex teal, Gemini indigo — placeholders; swap for official tokens). It is the only brand-colored element; everything else is pace-driven. In monochrome mode the dot desaturates with everything else, true to macOS.

Hero metric = % budget remaining. The LLM name + window label (“5-hour limit” / “7-day limit”) sit top-left; pace badge top-right.

5 · Pace & projection logic

Quantity	Definition
`idealNow`	Budget you should have left = `100 × (1 − tNow)`, where `tNow ∈ [0,1]` is position through the window.
`margin`	`actual − idealNow`. Positive = conserving, negative = over pace. Drives the badge and accent color.
`slope`	Recent burn rate (%/window) from the last two samples. Projection = extend this to 0%.
`runsOut`	True when the projection reaches 0% before reset. Only then does the widget show a red “Runs out in ~Xh Ym”; otherwise “Runs out: after reset”.

Reset countdown always shows (“Resets in 2h 06m” / “Resets in 3d 4h”). The estimated run-out time is surfaced only when it lands before reset, since that's the actionable case.

6 · Edge states

State	Behavior
Fresh — window just reset	Hero `100%`, badge “full” (◆), now-node near the left edge, “Runs out: after reset”. Neutral, no alarm.
Depleted — budget spent before reset	Hero `0%` in red, badge “spent” (■), actual line resting flat on the baseline, “Ran out: budget spent” in red. Reset countdown keeps running.
Now at window edges	Node clamps inside the plot; axis labels (start / now / reset) never overlap — “now” hides if within ~12% of an end label.

7 · Type scale & tokens

Element	Size / weight	Notes
Hero % remaining	`41px / 660`, `-1.2` tracking	tabular-nums; red when depleted
LLM name	`14.5px / 680`	with brand dot
Pace badge (±%)	`14px / 680`	pace color + ▲▼● glyph
Stat rows / labels	`12.5px / 11.5px`	tabular-nums values
Window label / axis	`11px / 9.5px`	sub color
Corner radius	`24px`	container; `13–15px` padding

All colors authored in OKLCH so luminance is tunable independently of hue — essential for hitting contrast targets across the four mode combinations.

8 · Build exactly these

The canonical render set — the complete target. Every other arrangement in the exploration canvas is superseded by this list. Widgets shown on a colorful desktop scene so the monochrome desaturation is visible.

9 · Explored but out of scope

Seen in the exploration canvas; do not implement. Kept only as a record of directions considered.

Per-brand “tinted monochrome” treatment — tinting the whole widget in each LLM's hue (Claude clay, Codex teal, Gemini indigo). Superseded: brand identity is the dot only; the widget body is pace-driven (§4).
“Status-driven” whole-material tint — tinting the entire background toward the pace color. Superseded by the Stocks-style approach where only the accent (line / hero / badge) carries pace, on a neutral material.