# Feature Specification: Tag Badge Catalog (Neutral, Suite-wide) v1

**Feature Branch**: `060-tag-badge-catalog`  
**Created**: 2026-01-22  
**Status**: Draft  
**Input**: Standardize non-status metadata badges (“tags/chips”) across the admin suite with consistent labels and a neutral palette, without changing any status/severity/health semantics.

## Clarifications

### Session 2026-01-23

- Q: Tag badge palette strategy → A: Neutral colors are assigned per tag domain (domain → color), consistent across the suite (not per individual tag value).
- Q: v1 migration coverage → A: v1 migrates the minimum targeted surfaces plus any additional tag-like badges found in the discovery sweep.
- Q: Unknown/unmapped tag value label → A: Show “Other: <value>” (normalized), so the value remains visible but clearly uncurated.
- Q: Canonical platform label casing → A: Use Title Case labels (Windows, Android, iOS, macOS, All).
- Q: Scope of “neutral palette” → A: Use an explicit allowlist of neutral colors only: gray, primary, info.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Read policy metadata clearly (Priority: P1)

An administrator browsing policy lists can quickly understand policy metadata (type, category, platform, visibility) via consistent tag badges that do not imply health or risk.

**Why this priority**: Policy inventory is a primary workflow; inconsistent tag styling causes repeated confusion and slows review.

**Independent Test**: On the Policies list, tag badges are consistent (label + neutral color) for the same values across multiple rows, and none appear as “success/warning/danger” style indicators.

**Acceptance Scenarios**:

1. **Given** a Policies list with mixed policy types, **When** the user views the list, **Then** each policy’s type/category/platform appears as a neutral tag badge with a canonical label.
2. **Given** a Policies list that includes archived and active items, **When** the user views the list, **Then** visibility tags are clearly labeled and do not use health/status colors.

---

### User Story 2 - Consistent tags across key surfaces (Priority: P2)

An administrator sees the same tag values rendered the same way across the suite (lists, detail views, and dashboard snippets), so they can switch between areas without re-learning color meanings.

**Why this priority**: Inconsistency across surfaces makes the UI feel unreliable and increases misinterpretation of metadata.

**Independent Test**: On each targeted surface, the same tag value (e.g., “Windows” platform) renders with the same label and neutral styling.

**Acceptance Scenarios**:

1. **Given** an inventory item and a policy version that share a platform value, **When** the user views both pages, **Then** the platform tag badge matches in label and neutral styling.
2. **Given** a tenant list that includes multiple environments, **When** the user views the list, **Then** environment tags are neutral and consistent across rows.

---

### User Story 3 - Prevent regressions (Priority: P3)

The product team can extend or refine tag display rules without reintroducing ad-hoc badge styling across individual pages.

**Why this priority**: Without guardrails, inconsistent tag colors tend to reappear over time as new pages and fields are added.

**Independent Test**: A change that introduces a non-neutral tag color is detected by automated validation.

**Acceptance Scenarios**:

1. **Given** a newly introduced tag value, **When** it is displayed anywhere in the admin UI, **Then** it uses a neutral color and a canonical label (or a neutral fallback if unmapped).
2. **Given** a change that attempts to render a tag badge using a reserved health/status color, **When** automated validation runs, **Then** it fails with a clear signal that the neutral palette rule was violated.

### Edge Cases

- Unknown tag values (new/rare values): show a neutral badge labeled “Other: <value>” (normalized).
- Missing metadata values: no misleading empty badge is shown; the UI handles absence gracefully.
- Confusable values (e.g., “active” as lifecycle vs status): tag meaning is based on field context, not the label itself.
- Mixed casing/source formatting (e.g., `windows`, `Windows`, `WINDOWS`): the displayed label is consistent.
- Very long labels: tags remain readable without breaking layout or implying urgency.

## Requirements *(mandatory)*

**Constitution alignment:** This feature changes UI presentation only. It must not add external API calls, background work, or any write behavior simply by viewing pages.

**Badge semantics alignment:** This feature standardizes tag-like (metadata) badges only. Status-like badges (status/outcome/severity/risk/availability/boolean) remain governed by the existing centralized status badge semantics.

### Scope

**In scope**

- Standardize suite-wide display rules for non-status metadata tags (e.g., policy type/category, platform, tenant environment, visibility, snapshot type).
- Apply consistent, neutral tag badges across key admin surfaces where metadata badges are shown, plus additional tag-like badges discovered during the discovery sweep.

**Out of scope**

- Changing business meaning or introducing new tag values (beyond canonical label casing).
- Re-standardizing status/severity/health/workflow badges (handled separately).
- Any layout or information-architecture redesign beyond badge rendering consistency.

### Functional Requirements

- **FR-001**: System MUST provide a single source of truth for tag badge display rules (label + neutral color + optional icon) grouped by tag domain (e.g., policy type, platform).
- **FR-002**: System MUST render all tag-like badges via the centralized catalog on targeted surfaces (tables, detail views, and dashboard lists) where metadata badges are shown.
- **FR-003**: Tag badges MUST use a neutral palette and MUST NOT use the suite’s reserved health/status colors (e.g., green/yellow/red semantics). The neutral palette MUST be an explicit allowlist: gray, primary, info.
- **FR-003a**: Tag badge colors MUST be assigned per tag domain (domain → color) and remain consistent across the suite.
- **FR-004**: System MUST keep a hard separation between tag-like badges (metadata) and status-like badges (health/workflow/severity). This feature MUST NOT change status-like badge meaning, color, or wording.
- **FR-005**: System MUST provide canonical, consistent labels for mapped tag values (including consistent casing).
- **FR-005a**: Platform tag labels MUST use Title Case: “Windows”, “Android”, “iOS”, “macOS”, and “All”.
- **FR-006**: System MUST provide a neutral fallback for unknown/unmapped tag values that remains readable and does not imply health or risk. The fallback label MUST be “Other: <value>” (normalized).
- **FR-007**: The initial rollout MUST cover, at minimum: Policies, Policy Versions, Inventory, Tenants, and any backup/snapshot metadata badges already displayed in the suite, plus any additional tag-like badges discovered during the discovery sweep.
- **FR-008**: System MUST include automated guardrails that detect ad-hoc tag badge styling and enforce the neutral palette rule for tag-like badges.
- **FR-009**: Viewing pages with tag badges MUST NOT trigger external requests or background work beyond the page’s normal data load.
- **FR-010**: The centralized catalog MUST cover, at minimum, these tag domains: policy type, policy category, platform, tenant environment, visibility/lifecycle, and snapshot type.

### Assumptions

- Feature 059 (centralized status + severity badges) is available and remains the source of truth for all status-like badges.
- Existing tag values are reused; this feature standardizes presentation and canonical label casing only.
- The suite has a consistent understanding of “tag-like” metadata fields versus “status-like” fields; any ambiguous field is treated as status-like and excluded from this feature.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: On all targeted surfaces, 100% of tag badges use only the approved neutral palette (gray, primary, info), verified via automated validation and spot-check QA.
- **SC-002**: In an internal review, at least 90% of administrators report that tag badges read as metadata and do not confuse them with health/status signals.
- **SC-003**: For each canonical tag domain (policy type/category, platform, tenant environment, visibility, snapshot type), the same value is displayed with the same label across at least two different areas of the suite.
- **SC-004**: Viewing pages containing tag badges does not introduce additional side effects (no unexpected external requests or background work triggered by badge rendering), verified via test/QA observation.
