From afc5f14181264a700e6e9f61a18e775c3c1e0a0b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 27 Aug 2026 09:49:30 +0000 Subject: [PATCH] docs: add three web UI visual refresh concepts as viewable prototypes The web UI has grown feature by feature and its visual language has not been revisited since it was a single labels table. Rather than argue about a refresh in the abstract, this adds three static prototypes that can be opened in a browser and compared side by side, each answering the same brief in a different way: token-level polish that keeps the DOM, a Home Assistant-native re-layout so the ingress panel stops looking like a separate product, and a density-first operator console aimed at the 400-group installs. The README records what each concept costs to implement, what it gives up, and the constraints any refresh has to respect - single file with no build step, no CDN for fonts or icons, an ingress iframe that cannot read the HA theme, and the iOS zoom and touch-target rules already in the shipped CSS. No production code is touched; public/index.html is unchanged. Co-authored-by: Doug Rathbone --- docs/design/web-ui-refresh/README.md | 158 ++++ .../screenshots/a-refined-labels.png | Bin 0 -> 125562 bytes .../screenshots/a-refined-phone.png | Bin 0 -> 58706 bytes .../screenshots/b-ha-native-labels.png | Bin 0 -> 86543 bytes .../screenshots/b-ha-native-phone.png | Bin 0 -> 63142 bytes .../screenshots/c-console-labels.png | Bin 0 -> 125543 bytes .../screenshots/c-console-phone.png | Bin 0 -> 75787 bytes .../screenshots/current-labels.png | Bin 0 -> 100364 bytes .../web-ui-refresh/variation-a-refined.html | 692 ++++++++++++++++++ .../web-ui-refresh/variation-b-ha-native.html | 611 ++++++++++++++++ .../web-ui-refresh/variation-c-console.html | 684 +++++++++++++++++ 11 files changed, 2145 insertions(+) create mode 100644 docs/design/web-ui-refresh/README.md create mode 100644 docs/design/web-ui-refresh/screenshots/a-refined-labels.png create mode 100644 docs/design/web-ui-refresh/screenshots/a-refined-phone.png create mode 100644 docs/design/web-ui-refresh/screenshots/b-ha-native-labels.png create mode 100644 docs/design/web-ui-refresh/screenshots/b-ha-native-phone.png create mode 100644 docs/design/web-ui-refresh/screenshots/c-console-labels.png create mode 100644 docs/design/web-ui-refresh/screenshots/c-console-phone.png create mode 100644 docs/design/web-ui-refresh/screenshots/current-labels.png create mode 100644 docs/design/web-ui-refresh/variation-a-refined.html create mode 100644 docs/design/web-ui-refresh/variation-b-ha-native.html create mode 100644 docs/design/web-ui-refresh/variation-c-console.html diff --git a/docs/design/web-ui-refresh/README.md b/docs/design/web-ui-refresh/README.md new file mode 100644 index 0000000..b27f4bc --- /dev/null +++ b/docs/design/web-ui-refresh/README.md @@ -0,0 +1,158 @@ +# Web UI visual refresh - three concepts + +Three self-contained prototypes of what a visual refresh to the cgateweb web UI +(`public/index.html`) could look like. Each is a static HTML file with fake data: +nothing is wired to the API, so they are safe to open anywhere. + +``` +docs/design/web-ui-refresh/ + variation-a-refined.html Same layout, new design tokens + variation-b-ha-native.html Looks like part of Home Assistant + variation-c-console.html Dense operator console +``` + +Open a file directly in a browser. Both variations accept two query parameters: +`?theme=dark` or `?theme=light` to force a palette, and `?tab=status|labels|events|import` +to land on a specific view. There is also a Theme button in each prototype. + +## What the refresh is trying to fix + +![The UI today](screenshots/current-labels.png) + +The current UI works, and none of this is about features. The observations that +drove all three concepts: + +- **Connection state reads as plain text.** On the Status tab, "connected", + "1.22.3" and "0" are all rendered at the same size and weight, so the eye has + nothing to lock onto. Whether the bridge is healthy should be answerable in a + glance, and today it takes a read. +- **Health is only visible on one tab.** You have to leave the device table to + find out that MQTT dropped. +- **The palette is generic.** The blue is Mantine's default rather than Home + Assistant's, so inside an ingress iframe the panel looks like a different + product bolted into HA. +- **The device table is styled loosely for its job.** Zebra striping plus row + hairlines plus a header underline is three separators doing one job, while the + addresses - the thing people actually scan - get no visual distinction from + labels. +- **Density is neither compact nor comfortable.** Rows are 6px-padded but the + type is 0.9rem, which gives a cramped-yet-tall row. A 418-group install shows + very few rows per screen. +- **Mobile degrades by hiding columns.** It works, but the Entity ID and Type + columns silently disappear, and the remaining table still needs sideways + scrolling on a phone. + +## Variation A - "Refined" + +![Variation A, device labels](screenshots/a-refined-labels.png) + +Same layout, same DOM, new design tokens. Tabs become a segmented control, +cards get a larger radius and a real elevation token, the status tiles gain +coloured state dots so connection state is pre-attentive, addresses become +monospace chips, zebra striping is dropped in favour of hairlines plus a hover +tint, and badges become pills. Buttons get a visible hierarchy (filled primary, +outlined secondary, ghost tertiary) instead of three near-identical greys. + +**Cost:** the ` + + +
+
+
+
CB
+
+

C-Bus Web

+
cgateweb · 1.22.3
+
+
+
+ + + + +
+
+ +
+ + + + +
+ +
+
Bridge health
+
+
Version
1.22.3
+
Uptime
4d 6h 12m
+
Ready
yes
+
Lifecycle
running
+
Reason
—
+
MQTT
connected
+
Event
connected
+
Reconnects
0
+
Cmd Pool Healthy
3 / 3
+
Queue Depth
0
+
C-Bus Networks (CNI)
254 · 192.168.1.50
+
+
+
Labels 418
+
Custom 37
+
Overrides 12
+
Excluded 5
+
Unsaved 0
+
+
+ +
+
+
+ + +
+ + +
+ +
+ 2 selected +
+ Set type: + +
+ +
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Address ▲LabelTypeEntity IDAreaExcl
254/56/1Kitchen Downlightslight.kitchen_downlightsKitchenunsaved
254/56/2Kitchen PendantsautoKitchen
254/56/4Living Room LampsautoLiving Room
254/56/12Hallway SconcesautoHall?
254/203/1Living Room Blindscover.living_blindsLiving Room
254/56/33Garage Door RelayautoGarage
254/56/40Alfresco FloodautoAlfresco
254/202/5Scene: Movie NighttriggerautoLiving Room
+
+ +
+ + + Showing 1–8 of 418 devices + +
+ +
+ + + + +
+
+ +
+
+ + + 126 + +
+
+ + + + + + + + + + +
TimeAddressLabelLevelBar
09:24:16254/56/1Kitchen Downlights100%
09:24:11254/56/4Living Room Lamps64%
09:23:58254/203/1Living Room Blinds40%
09:23:41254/56/12Hallway Sconces0%
09:23:02254/56/33Garage Door Relay100%
09:22:47254/56/2Kitchen Pendants25%
+
+
+ +
+
Project file
+
+ Drop a .cbz or .xml project file here +

or click to browse. Labels, areas and device types are read from the Toolkit project.

+ +
+
+ + +
+
+ +
Design prototype — Variation A "Refined". Static mock, not connected to the bridge.
+
+ + + + diff --git a/docs/design/web-ui-refresh/variation-b-ha-native.html b/docs/design/web-ui-refresh/variation-b-ha-native.html new file mode 100644 index 0000000..64804b9 --- /dev/null +++ b/docs/design/web-ui-refresh/variation-b-ha-native.html @@ -0,0 +1,611 @@ + + + + + +Variation B - Home Assistant Native - cgateweb design prototype + + + + +
+
+

C-Bus Web

+ + + + +
+
+ + + + +
+
+ +
+
+
+
Bridge
+
cgateweb 1.22.3 · up 4 days, 6 hours
+
+
+
+
Bridge ready
Lifecycle: running
+
Yes
+
+
+
+
MQTT broker
core-mosquitto:1883 · 0 reconnects
+
Connected
+
+
+
+
C-Gate event connection
port 20025
+
Connected
+
+
+
+
Command pool
Queue depth 0
+
3 / 3 healthy
+
+
+
+
C-Bus network 254
CNI 192.168.1.50:20023
+
Online
+
+
+
+
418
Labels
+
37
Custom
+
12
Overrides
+
5
Excluded
+
0
Unsaved
+
+
+
+ +
+
+
+
+ + +
+ +
+
+ + + + + + +
+ +
+ 2 selected + + + + + + +
+ +
+ + Kitchen 2 devices +
+
+ +
+
+
Kitchen Downlights
+
254/56/1 · light.kitchen_downlights unsaved
+
+
+ + +
+
+
+ +
+
+
Kitchen Pendants
+
254/56/2 · entity ID auto
+
+
+ + +
+
+ +
+ + Living Room 3 devices +
+
+ +
+
+
Living Room Lamps
+
254/56/4 · entity ID auto
+
+
+ + +
+
+
+ +
+
+
Living Room Blinds
+
254/203/1 · cover.living_blinds
+
+
+ + +
+
+
+ +
+
+
Scene: Movie Night
+
254/202/5 trigger
+
+
+ +
+
+ +
+ + Garage 1 device +
+
+ +
+
+
Garage Door Relay
+
254/56/33 · entity ID auto
+
+
+ + +
+
+ +
+ + Not exposed to Home Assistant 1 device +
+
+ +
+
+
Alfresco Flood
+
254/56/40 · Alfresco excluded
+
+
+ +
+
+ + +
+ + +
+
+
+ +
+
+
Live events
+
+
+ + +
+ Live · 126 events + + +
+
+
+
09:24:16
+
+
Kitchen Downlights turned on, brightness 100%
254/56/1
+
+
+
09:24:11
+
+
Living Room Lamps ramped to 64%
254/56/4
+
+
+
09:23:58
+
+
Living Room Blinds opened to 40%
254/203/1
+
+
+
09:23:41
+
+
Hallway Sconces turned off
254/56/12
+
+
+
09:23:02
+
+
Garage Door Relay turned on
254/56/33
+
+
+
+
+ +
+
+
Import project
+
Load labels, areas and device types from a C-Bus Toolkit project file.
+
+
Drop a .cbz or .xml file here
+

or choose a file to upload. Existing labels can be merged or replaced.

+ +
+
+
+
Export
+
+
+
Label backup
JSON snapshot of all labels, types and areas
+ +
+
+
+
Project XML
Re-exported C-Bus project for Toolkit
+ +
+
+
+ +
Design prototype — Variation B "Home Assistant Native". Static mock, not connected to the bridge.
+
+ + + + diff --git a/docs/design/web-ui-refresh/variation-c-console.html b/docs/design/web-ui-refresh/variation-c-console.html new file mode 100644 index 0000000..26cf9bf --- /dev/null +++ b/docs/design/web-ui-refresh/variation-c-console.html @@ -0,0 +1,684 @@ + + + + + +Variation C - Operator Console - cgateweb design prototype + + + + +
+ + +
+
+
Devices 418 groups · network 254
+
+ MQTT + C-Gate + Pool 3/3 + Queue 0 + Uptime 4d 6h + + + + +
+
+ + +
+
+
+ + +
+
+ + +
+ + 418 rows · 8 shown +
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Address ▲LabelTypeEntity IDAreaFlags
254/56/1Kitchen Downlightslightlight.kitchen_downlightsKitchenunsaved
254/56/2Kitchen PendantslightautoKitchen
254/56/4Living Room LampslightautoLiving Room
254/56/12Hallway SconceslightautoHall?
254/203/1Living Room Blindscovercover.living_blindsLiving Room
254/56/33Garage Door RelayswitchautoGarage
254/56/40Alfresco FloodlightautoAlfrescoexcluded
254/202/5Scene: Movie NighttriggerautoLiving Room
+
+ + +
+ +
+ 2 selected + + Set type + + + + + + + + ↑↓ move   Space select   E edit + +
+
+ + +
+
+
+
+
Uptime
+
4d 6h 12m
+
+
+
Events / min
+
42
+ + + +
+
+
Queue depth
+
0 peak 6
+ + + +
+
+
Command pool
+
3 / 3 healthy
+
+
+
Reconnects (24h)
+
0
+
+
+
Version
+
1.22.3
+
+
+ +
+
Connections
+
+ + MQTT broker + core-mosquitto:1883 + connected · 4d 6h +
+
+ + C-Gate command pool + 192.168.1.20:20023 + 3 connections +
+
+ + C-Gate event stream + 192.168.1.20:20025 + connected +
+
+ + CNI network 254 + 192.168.1.50 + online +
+
+ +
+
Label store
+
Total labels418
+
Custom labels37
+
Type overrides12
+
Excluded from discovery5
+
Unsaved changes0
+
+
+
+ + +
+
+
+ + +
+ + + streaming · 126 events · 42/min +
+
+
09:24:16.4254/56/1Kitchen Downlights100%
+
09:24:11.9254/56/4Living Room Lamps64%
+
09:23:58.1254/203/1Living Room Blinds40%
+
09:23:41.7254/56/12Hallway Sconces0%
+
09:23:02.3254/56/33Garage Door Relay100%
+
09:22:47.0254/56/2Kitchen Pendants25%
+
09:22:31.6254/56/4Living Room Lamps80%
+
09:22:04.2254/202/5Scene: Movie Nighton
+
09:21:52.8254/56/1Kitchen Downlights55%
+
09:21:30.5254/56/12Hallway Sconces100%
+
+
+ + +
+
+
+
Drop a .cbz or .xml project file
+

Labels, areas and unit types are parsed from the Toolkit project. Merge or replace on import.

+ +
+
+
Export
+
+ Label backup + JSON · labels, types, areas, exclusions + +
+
+ Project XML + C-Bus Toolkit compatible + +
+
+
+
+ +
Design prototype — Variation C "Operator Console". Static mock, not connected to the bridge.
+
+
+ + + +