ADR-001-c — Hour Color Vocabulary

ADR-001-c — Hour Color Vocabulary

Status

Accepted

Context

Five color terms describe the nature of hours at unit and employee level. They are shared vocabulary for dashboards and documentation, not formal model fields. This ADR defines the terms, coexistence rules, and mapping to API enums.

Decision

Colors. Five colors form the shared vocabulary for dashboards and documentation.

Color	Meaning
🟢 Green	Position exactly covered (100%). Employee contract fully consumed.
🔴 Red	Unfulfilled hours — typically vacancies.
🟡 Yellow	Partially covered position (>0%, <100%).
🔵 Blue	Intentional reinforcements only (Refuerzo slots). Not accidental over-assignment.
⚪ Grey	Cancelled or undefined — outside computation.

Coexistence. Yellow, red, and blue can coexist in a unit. Green is exclusive: all positions must be COVERED. One PARTIAL or VACANT breaks green even if aggregate = 100%. Per-employee: green = contract hours fully consumed with no excess.

Totalization. The following rules are the single source of truth for any component that calculates or displays aggregated hours at the unit or org-unit level.

Rule 1 — Green is exclusive. If all positions in the unit have CoverageState = COVERED (exactly 100%), the total color is green. No other category can coexist with green at the unit level. A single PARTIAL or VACANT breaks green even if the aggregate percentage reaches 100%.

Rule 2 — Red is always shown separately. Red hours (positions with VACANT) are counted and rendered independently from other colors. They are not merged with yellow nor offset by blue.

Rule 3 — Yellow and blue are additive. They can coexist in the same unit. They are summed to produce the total coverage percentage for non-green positions.

Rule 4 — Dominant color of the total when yellow and blue coexist:

• Yellow only (no blue) → total color: yellow.
• Blue only (no yellow) → total color: blue.
• Yellow + blue with aggregate total >= 100% → total color: blue (reinforcements compensate or exceed the deficit).
• Yellow + blue with aggregate total < 100% → total color: yellow (there is a net deficit despite reinforcements).

Rule 5 — Coverage bar composition. The bar is built left to right in this order: green (or yellow), blue, red/gray. The red/gray segment (deficit) always occupies the rightmost end of the track when present. Blue is placed before the deficit to visually communicate that it represents extra hours above the base demand — not a gap. This rule guarantees that the gray area (vacant/deficit) is always the “empty” portion at the end of the bar.

Enum mapping. Colors are a semantic overlay, not 1:1 with API enums:

Color	CoverageState	Balance	Key distinction
Green	COVERED	BALANCED	—
Yellow	PARTIAL	—	Position-scoped only
Red	VACANT	—	Broader than VACANT — any unfulfilled hours
Blue	≠ OVER_COVERED	≠ SURPLUS	Blue = intentional reinforcements only
Grey	—	—	Outside computation

“Excedente” disambiguation. Three distinct scopes — do not conflate:

1. Position = OVER_COVERED (>100% assigned vs required)
2. Employee = SURPLUS (assigned > obligated)
3. Blue hours = reinforcements via Refuerzo slots (demand-side mechanism)

Consequences

• Totalization rules (Rules 1–5 above) govern how colors combine at unit level. OrgChartDetail, CoverageBar, and any KPI widget that displays aggregated hours must implement them consistently. Rule 4 defines a single discrete color state per unit, eliminating ambiguity in tooltips, badges, and exports. Rule 5 fixes the segment order in the bar — red/gray cannot appear between yellow and blue.
• [[adr-024-employee-bar-semantics-and-contract-matching|ADR-024]] specifies employee-level bar semantics.
• New colors or rule changes require a new ADR.