Progress Bar UX

Three things a progress bar must do to feel right:

1. Fill bottom-up. It's a thermometer. Liquid rises, it does not fall. If your hardware is indexed top-to-bottom (Govee segments, LED strips, etc.) you must invert the index when lighting cells.
2. Red → Yellow → Green gradient as the value increases from 0 to 1.
3. Do not use Python list iteration order to decide which cell to light first. That gives you a top-down fill and every user will tell you it feels wrong.

Mapping a value in [0, 1] to a segmented bar

Given total_segments:

lit = int(round(value * total_segments))

If hardware has segment 0 at the top (e.g. Govee H6056):

# bottom-up fill: the lit cells are the high indices
segments_to_light = range(total_segments - lit, total_segments)

If hardware has segment 0 at the bottom:

segments_to_light = range(0, lit)

Gradient

Two-stop gradient through yellow:

def gradient_rgb(t: float) -> tuple[int, int, int]:
    t = max(0.0, min(1.0, t))
    if t < 0.5:
        return (255, int(255 * (t * 2)), 0)          # red -> yellow
    return (int(255 * (1 - (t - 0.5) * 2)), 255, 0)  # yellow -> green

See scripts/progress_bar.py for the reference implementation. Import fill_segments(value, total, top_index_is_zero) and you cannot get the direction wrong.

How to act

1. Any time you render a bar — terminal, GUI, physical LEDs — use fill_segments.
2. Remove any code that iterates for i, seg in enumerate(segments) to light cells in order. That's a top-down fill in disguise.
3. If a designer asks for top-down fill, explain the thermometer convention — liquid-style bottom-up fill is what users expect.
4. Verify direction: After wiring up the bar, test with value=0.1 and confirm only the bottom segment lights up. Flip the top_index_is_zero argument if not.

When paired with debounce-controller

The target you pass to ctrl.set_target(...) should already be quantised to int(round(value * total_segments)) — not the raw float. See the target-quantization skill in this plugin.

Related

• debounce-controller — the actuator pattern usually paired with this UI pattern
• target-quantization — discrete targets are a prerequisite for debounce stability