bluerobotics / bluerobotics/cockpit

frontend: document a Cockpit design system so UI conventions stop living only in review comments

Open
#2,884 0 comments 1 reaction 1 assignee Claimed by @ArturoManzoli View on GitHub
documentation ui ux
Dominant language
TypeScript
Stars
198
Forks
63
Avg merge
2d 7h
Merged PRs (30d)
57

Description

## Problem

I went through the review comments of the last 100 merged PRs. The largest single category of human review effort is visual/UX polish against conventions that are not written down anywhere — there is no design-system or style-guide document in the repo.

The consequence is that the same checklist gets retyped by hand on almost every PR that adds a dialog. From #2848, #2783, #2777, #2815 and #2761, the recurring modal review is always some subset of:

- centered modal title
- X button on the top right, vertically aligned with the title, equal top and right margins
- cancel button on the left side of the footer
- primary button with `#FFFFFF33` background and white text
- footer separator line present, reduced footer height, buttons vertically centered in it
- no upper divider

Beyond modals, the same thing happens with:

- **Sunlight readability.** The accent green had to be darkened 25% to `#3B7B62` in #2853 because most of our use cases are in highly illuminated areas. Same class of finding in #2733 (red stop button invisible, needed white text or `#FFFFFF22`/`#FFFFFF33` background) and #2685 (fallback tile text needed a bigger font, an outline, and viewport-relative sizing to stay legible).
- **Vertical-space economy.** Group related settings into an `ExpansiblePanel`, lay fields out in a two-column grid on non-phone screens (#2729, #2815).
- **Icon semantics and optical sizing.** `mdi-download-multiple` reads as "download" where a zip icon does not (#2819); icons of the same numeric size look different depending on shape and fill, so they need optical adjustment (#2777).
- **Table conventions.** Selection columns go first or last, not in the middle (#2777).
- **Component defaults.** `theme=\"dark\"` on selectors (#2815).
- **Spacing nudges.** Recurring "move this up 3-4px", "add 10px here", "same margins top and right" comments across #2761, #2819, #2783.

## Why it matters

Two costs. First, reviewers spend most of their review budget re-deriving and re-typing conventions instead of looking at logic. Second, our automated PR reviewer (`.github/claude-review/review-guidelines.md`) cannot check any of this — section 5 only says "consistency with existing widgets and UI patterns", which is too vague to produce a finding. Every one of the items above reached master and had to be caught by a human.

## Proposal

A written design-system reference covering at minimum:

1. Modal/dialog anatomy (title, close affordance, footer, button placement and styling)
2. The color palette with the actual approved values, and the sunlight-readability constraint behind them
3. Spacing and alignment scale
4. Icon set conventions and optical sizing guidance
5. Table/list conventions
6. Density and vertical-space guidance, including the mobile and small-screen cases

Once that exists, we can reference it from `AGENTS.md` and add concrete checks to the automated reviewer's UI/UX section, so these stop being caught by hand.

## Note

@ArturoManzoli — from the last internal meeting, you mentioned you are already working on something along these lines. Opening this so the need is tracked and so the review-guidelines work can point at it once it lands. Feel free to reshape the scope above to match what you already have in progress.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.