Story: Badge colour scheme: visual polish and self-badging fixes

Table of Contents

This page documents a story in Sprint 24. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Split from Improve badge colour scheme support (Sprint 23) at close: that story shipped its core deliverable — the badge_mapping browser UI and the migration of badge_definition=/=badge_severity=/ =code_domain onto standard codegen + DQ publishing — but left two concrete, scoped defects unfixed:

  1. The Badge Definitions/Severities admin UI shows colours as plain hex text instead of swatches, so semantic misuse of the grey/green/red/yellow convention can't be eyeballed, and the unmapped-value fallback colour is still a hardcoded Qt-only constant instead of a real badge_definition row.
  2. An entity that is a badge source (e.g. book_status) doesn't badge itself on its own list — only consumers of it do.

Both are small, well-understood fixes, not open-ended discovery — distinct from the coverage-audit-and-rollout work split into Classify and roll out badge/image/plain-text rendering across domain entities.

Status

Field Value
State DONE
Parent sprint Sprint 24
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-07-30

Acceptance

  • badge_definition=/=badge_severity admin UI renders colours as swatches (not hex text), with a colour picker in the detail dialog.
  • The unmapped-value fallback is a real, reserved badge_definition row, resolved through BadgeCache like any other badge, visually distinct from a legitimate grey/inactive badge.
  • At least one badge-source entity (e.g. book_status) badges itself on its own list, via an explicit codegen model annotation (not DB introspection).
  • No regression to any currently-working badge rendering.

Tasks

Task State Start End Description
Badge palette swatch rendering + data-driven fallback badge DONE 2026-07-22 2026-07-26 Colour-swatch delegate and picker for Badge Definitions/Severities admin UI; replace the hardcoded Qt fallback constant with a real, reserved badge_definition row.
Badge sources should badge their own list too DONE 2026-07-28 2026-07-28 Codegen mechanism so a badge-source entity's own code/name column also gets badge_key wired to its own code_domain.
Close story: badge colour scheme visual polish and self-badging fixes DONE 2026-07-30 2026-07-30 Both tasks (badge palette swatch rendering + fallback, badge source self-annotation) are DONE; close the story out.

Decisions

  • Colour fields get a dedicated colour codegen detail-field type (swatch button + QColorDialog) rather than a raw line_edit with hex text – any future entity needing a colour picker inherits this for free.
  • A column that is a colour (e.g. background_colour) gets its own self-colour list-column style, distinct from is_badge (which resolves a code through BadgeCache) – the two facets model different relationships (own value vs. lookup) and must not be conflated.
  • The fallback for an unresolved badge is a real, reserved badge_definition row (code'unmapped'), not a second hardcoded constant living alongside =ColorConstants::badge_fallback – every client/delegate resolves it through BadgeCache::fallback() the same way it resolves any other badge, and it gets a dashed-border treatment so it never reads as a legitimate grey/inactive badge.
  • Qt-client caches that need to stay fresh (BadgeCache, ChangeReasonCache) subscribe directly to their NATS change-event(s) via ClientManager and reload on receipt, re-subscribing on login/reconnect – this is a different, GUI-tier pattern from the server-side entity-mirror cache facet (see How does a Qt client cache stay fresh?), not a shared mechanism.

Out of scope

  • The badge adoption coverage audit and rollout across domain_entity models — see Classify and roll out badge/image/plain-text rendering across domain entities.
  • Wt-side badge rendering — carried over as out of scope from the parent story (explicit user instruction).
  • A manual QA * Test Scenarios pass against a live client for either sibling task – both shipped with build + unit-test verification only. Closed at explicit instruction rather than left open pending QA; worth a live-client pass later if the swatch rendering/fallback badge/self-badging behaviour is ever in question.

Emacs 29.3 (Org mode 9.6.15)