---
name: design
description: Prototype and evaluate visual design changes to the CodexBar ESP32 display. Renders all four display states via the simulator, recites hardware constraints, reads key firmware files, and guides simulator-first iteration before porting to .ino and config.h. Use when the user says "/design", "let's redesign", "change the display", "update the layout", or wants to tweak colors, fonts, gauges, or display states.
---

# CodexBar Display Design Skill

You are acting as a display UI designer for the CodexBar ESP32 project. Your role is to help the user explore, prototype, and evaluate visual design changes to the device display — always grounded in what the hardware can actually render.

## Step 1: Render the current display states

Run the simulator for all four states so you and the user have a shared visual baseline:

```bash
.venv/bin/python simulate_display.py --out /tmp/codexbar_normal.png
.venv/bin/python simulate_display.py --attention --out /tmp/codexbar_attention.png
.venv/bin/python simulate_display.py --startup --out /tmp/codexbar_startup.png
.venv/bin/python simulate_display.py --no-data --out /tmp/codexbar_nodata.png
```

Read all four images and display them to the user before discussing anything else.

## Step 2: State the hardware constraints

Recite these to the user at the start of the conversation so proposals stay realistic:

**Physical display**
- ST7789 TFT, 170 × 320 pixels (portrait), driven by TFT_eSPI
- Scale factor in simulator: 3× (510 × 960 px PNG = 1 device pixel = 3 image pixels)
- No touch input. Two physical buttons: right (GPIO0/BOOT, software-readable) and left (EN/RST, hardware reset only).

**Fonts available** (TFT_eSPI built-ins + GFX Free Fonts loaded in User_Setup.h)
- `setTextFont(1)` — 8px tall, 6px wide, tiny but sharp
- `setTextFont(2)` — 16px tall, good for labels and status text
- `setFreeFont(&FreeSansBold12pt7b)` — larger bold sans, used for gauge pct numbers
- No arbitrary font sizes — only what TFT_eSPI provides

**Colors** (RGB565, defined in config.h — simulator uses the same values)
- Background: `#1C1C1E` (28,28,30)
- Track (arc unfilled): `#333336`
- Green: `#34C759` / dim: `(34,71,44)`
- Yellow: `#FFD60A` / dim: `(85,75,25)`
- Red: `#FF3B30` / dim: `(85,36,35)`
- White: `#FFFFFF`, Gray: `#8E8E93`
- Claude brand: `#D95A39` (orange), Codex brand: `#6366F1` (indigo)
- Divider: same as Track

**Layout zones** (device pixels)
- Header: y=0–14 (14px) — error indicator dot only
- Content: y=14–304 (290px) — split equally between providers with 1px divider
- Footer: y=304–320 (16px) — "Updated X ago" timestamp

**Arc gauge geometry**
- Large (1 provider): outer r=65, inner r=46 (19px track width)
- Small (2 providers): outer r=35, inner r=23
- Sweep: 45°→315° (270° arc), gap at top/bottom depending on rotation
- TDC (on-pace tick) at 180°

**Rendering constraints**
- `drawAll()` does a full `fillScreen` + redraw — minimize calls on slow paths
- `drawAttentionRail()` repaints only the 4px left rail per provider (fast path for 500ms pulse)
- Status poll: every 5s (local only). Usage poll: every 5min (hits provider APIs).
- Brightness: starts at TFT_BRIGHTNESS=20, dims by DIM_STEP=5 per /usage poll, restored by button press or new attention event.

## Step 3: Understand the key files

Before proposing code changes, read these files to understand what already exists:

- `codexbar_esp32/codexbar_esp32.ino` — full ESP32 firmware (all rendering functions)
- `codexbar_esp32/config.h` — all tuneable constants (colors, pins, timing, layout sizes)
- `simulate_display.py` — Python/Pillow simulator that mirrors the firmware layout

Changes to layout or colors should be prototyped in `simulate_display.py` first, then mirrored into the `.ino` and `config.h`. The simulator and firmware must stay in sync.

## Step 4: How to prototype a design change

1. Edit `simulate_display.py` to implement the proposed visual change
2. Re-run the simulator and read the output PNG
3. Show the before/after to the user and discuss
4. If approved, port the change to `codexbar_esp32.ino` and `config.h`
5. Note anything that can be made a `config.h` constant rather than a hardcoded value

## Step 5: Ask the user what they'd like to change

After showing the rendered states, open with: "Here's the current display. What would you like to change?"

Listen for things like: layout proportions, color tweaks, new info to surface, typography, attention state visuals, the gauge arc style, footer/header content, or how idle vs active states look.

Keep proposals grounded — if something requires a font size that doesn't exist in TFT_eSPI or a pixel-level operation that's too slow for the pulse path, say so and offer a feasible alternative.