TenantAtlas/specs/059-unified-badges/contracts/badge-semantics.md

Badge Semantics Contract — Unified Badge System (v1)

This feature does not introduce HTTP APIs. These contracts define stable UI semantics for status-like badges across the admin panel.

Scope (v1)

In scope (status-like)

• Status/health signals (for example: queued/running/completed; enabled/disabled; available/missing; acknowledged/new).
• Severity/risk signals (for example: drift finding severity).

Out of scope (v1)

• Tag/category chips (for example: policy type, platform, environment labels).

Canonical color meanings (v1)

• success: successful completion / safe / positive terminal meaning.
• warning: queued / needs attention / partial / caution.
• info: actively running / in progress.
• danger: failed / blocking / high risk.
• gray: neutral, unknown, or “not applicable”.

Invariants (v1)

• Success/completed outcomes must never render as warning/attention.
• Unknown values must render safely (neutral) and must not be misrepresented as success.
• Badge rendering must be tenant-safe and must not trigger outbound HTTP, queued work, or DB lookups beyond already-loaded data.

Canonical mappings (v1)

Drift finding severity

• low → neutral (gray)
• medium → caution (warning)
• high → high risk (danger)

Run-like states (minimum)

Run-like states must consistently convey:

• queued → caution (warning)
• running → in progress (info)
• succeeded/completed → success (success)
• partial → caution (warning)
• failed → failure (danger)