cve-dashboard/.kiro/specs/compliance-metric-grouping/requirements.md

Requirements Document

Introduction

The AEO Compliance page currently renders one metric health card per metric_id returned from the summary endpoint. Many metrics share the same base ID but differ by network variant suffix (e.g., -Corp, -Cust, -SpecBus) in the definitions reference table. This feature groups those variant entries into a single card per metric family, adds hover tooltips with metric descriptions for quick context, provides an info panel for full metric definitions, and ships a static JSON reference file containing the complete metric definitions data. The goal is to reduce card clutter, surface metric context to engineers unfamiliar with the metrics, and preserve the existing card-click filtering behavior.

Glossary

• Compliance_Page: The CompliancePage.js React component that renders metric health cards, team tabs, and the device violation table
• Metric_Family: A group of summary entries that share the same base metric ID (e.g., 5.2.5), regardless of network variant suffix
• Network_Variant: A suffix classification from the metric definitions table indicating which network a metric applies to — Corp, Cust, or SpecBus
• Variant_Pill: A small inline badge within a grouped metric card that displays a single network variant's suffix label and its compliance percentage
• Metric_Health_Card: The existing MetricHealthCard button component that displays a metric's compliance status, now extended to support grouped variants
• Worst_Status: The most severe compliance status among all variants in a Metric_Family, used to determine the card's overall border and status color
• Hover_Tooltip: A floating overlay that appears on mouse hover over a Metric_Health_Card, showing the metric title, business justification, and data sources
• Info_Icon: A small Info icon from lucide-react placed in the corner of each Metric_Health_Card that opens the Detail_Panel on click
• Detail_Panel: A slide-out or inline expandable section that displays the full metric definition including scope, filters, exclusions, and per-variant notes
• Metric_Definitions_File: A static JSON file shipped with the frontend containing structured metric definition data for all tracked metrics
• Design_System: The color palette, typography, component specs, and interaction patterns defined in DESIGN_SYSTEM.md
• Summary_Entry: A single row from the backend's /api/compliance/summary response, containing metric_id, team, compliance_pct, target, status, description, and category
• Device_Table: The lower section of the Compliance_Page that lists non-compliant devices, filterable by metric

Requirements

Requirement 1: Metric Family Grouping

User Story: As an engineer, I want metrics that share the same base ID to be consolidated into a single card, so that the compliance page is less cluttered and I can see the full picture for each metric family at a glance.

Acceptance Criteria

1. WHEN the Compliance_Page receives Summary_Entry data, THE Compliance_Page SHALL group entries by their base metric ID to form Metric_Family groups
2. THE Compliance_Page SHALL render one Metric_Health_Card per Metric_Family instead of one card per Summary_Entry
3. THE Metric_Health_Card SHALL display the base metric ID (e.g., 5.2.5) as the card title and the category name from the first entry in the group
4. THE Metric_Health_Card SHALL display one Variant_Pill for each Summary_Entry in the Metric_Family, showing the variant's team label and compliance percentage
5. WHEN a Metric_Family contains only one Summary_Entry, THE Metric_Health_Card SHALL display a single Variant_Pill — the layout scales naturally without special-casing
6. THE Metric_Health_Card SHALL determine its overall border color and status indicator using the Worst_Status among all variants in the Metric_Family
7. THE Metric_Health_Card SHALL display the shared target percentage from the Metric_Family entries
8. WHEN a user clicks a grouped Metric_Health_Card, THE Compliance_Page SHALL filter the Device_Table to show violations across all metric IDs belonging to that Metric_Family

Requirement 2: Variant Pill Display

User Story: As an engineer, I want to see each network variant's compliance percentage inside the grouped card, so that I can quickly identify which variant is underperforming.

Acceptance Criteria

1. THE Variant_Pill SHALL display the variant's distinguishing label (team name or suffix) and its compliance percentage in monospace font
2. THE Variant_Pill SHALL use a background tint derived from the variant's individual status color at low opacity, consistent with the Design_System badge pattern
3. WHEN a variant's status is not "Meets/Exceeds Target", THE Variant_Pill SHALL display a subtle glow dot matching the variant's status color to draw attention
4. THE Variant_Pill layout SHALL wrap to multiple rows when the Metric_Family contains more variants than fit on a single line

Requirement 3: Worst-Status Card Coloring

User Story: As an engineer, I want the grouped card to immediately show me if any variant is failing, so that I do not have to inspect each variant individually to find problems.

Acceptance Criteria

1. THE Metric_Health_Card SHALL compute the Worst_Status by selecting the most severe status from all Summary_Entry items in the Metric_Family, using the severity order: "Below 15% of Target" (worst) > "Within 15% of Target" > "Meets/Exceeds Target" (best)
2. THE Metric_Health_Card SHALL apply the Worst_Status color to its border, status pill text, and status dot
3. WHEN all variants in a Metric_Family meet or exceed the target, THE Metric_Health_Card SHALL display the "OK" status indicator with the success color

Requirement 4: Hover Tooltip for Quick Context

User Story: As an engineer unfamiliar with the metrics, I want to hover over a metric card and see a brief description, so that I can understand what the metric measures without disrupting my workflow.

Acceptance Criteria

1. WHEN a user hovers over a Metric_Health_Card for more than 300 milliseconds, THE Compliance_Page SHALL display a Hover_Tooltip positioned near the card
2. THE Hover_Tooltip SHALL display the metric title, a one-liner business justification, and the data sources required, sourced from the Metric_Definitions_File
3. THE Hover_Tooltip SHALL use the Design_System dark card background with a subtle border and shadow for readability
4. WHEN the user moves the cursor away from the Metric_Health_Card, THE Hover_Tooltip SHALL disappear
5. THE Hover_Tooltip SHALL NOT interfere with the card's click behavior for filtering the Device_Table
6. IF no definition exists in the Metric_Definitions_File for a given metric, THEN THE Hover_Tooltip SHALL display the metric description from the Summary_Entry data as a fallback

Requirement 5: Info Icon and Detail Panel

User Story: As an engineer, I want to click an info icon on a metric card to see the full metric definition, so that I can understand the exact scope, filters, and exclusions without leaving the compliance page.

Acceptance Criteria

1. THE Metric_Health_Card SHALL display an Info_Icon (lucide-react Info) in the top-right corner of the card
2. WHEN a user clicks the Info_Icon, THE Compliance_Page SHALL open a Detail_Panel displaying the full metric definition from the Metric_Definitions_File
3. THE Detail_Panel SHALL display: metric title, asset types in scope, application types in scope, environment in scope, status in scope, instance types in scope, criticality levels in scope, exclusions, special conditions, data sources required, business justification, and per-variant notes
4. THE Detail_Panel SHALL use the Design_System dark theme with section labels in monospace uppercase and content in the standard text colors
5. WHEN a user clicks the Info_Icon, THE click event SHALL NOT propagate to the Metric_Health_Card's onClick handler that filters the Device_Table
6. WHEN a user clicks outside the Detail_Panel or clicks a close button, THE Detail_Panel SHALL close
7. IF no definition exists in the Metric_Definitions_File for a given metric, THEN THE Detail_Panel SHALL display a "No detailed definition available" message with the Summary_Entry description as fallback content

Requirement 6: Metric Definitions Data File

User Story: As a developer, I want metric definitions stored as a static JSON file in the frontend, so that the tooltip and detail panel can render metric context without additional API calls.

Acceptance Criteria

1. THE Metric_Definitions_File SHALL be a JSON file located in the frontend source directory (e.g., frontend/src/data/metricDefinitions.json)
2. THE Metric_Definitions_File SHALL contain an entry for each metric ID with the following fields: metric_id, metric_title, asset_types, asset_types_in_scope, application_types_in_scope, environment_in_scope, status_in_scope, instance_types_in_scope, criticality_levels_in_scope, exclusions, special_conditions, data_sources_required, business_justification, and notes
3. THE Metric_Definitions_File SHALL be importable as a standard JavaScript module using a static import statement
4. WHEN the Metric_Definitions_File is loaded, THE Compliance_Page SHALL build a lookup map keyed by metric_id for efficient access
5. THE Metric_Definitions_File SHALL use a flat array structure where each entry represents one metric row from the definitions table

Requirement 7: Preserved Card-Click Filtering Behavior

User Story: As an engineer, I want clicking a grouped metric card to still filter the device table, so that the existing workflow for investigating violations is not disrupted.

Acceptance Criteria

1. WHEN a user clicks a grouped Metric_Health_Card (outside the Info_Icon), THE Compliance_Page SHALL set the metric filter to include all metric IDs in that Metric_Family
2. WHEN a metric filter is active for a Metric_Family, THE Device_Table SHALL display devices that have violations for any metric ID within that family
3. WHEN a user clicks the same grouped Metric_Health_Card again, THE Compliance_Page SHALL clear the metric filter
4. THE "clear filter" button in the metric health section header SHALL continue to reset the filter to show all devices
5. THE Metric_Health_Card SHALL visually indicate the active/selected state using the existing highlight pattern (tinted background with the status color)

Requirement 8: Metric Definitions File Structure and Round-Trip Integrity

User Story: As a developer, I want the metric definitions JSON to be parseable and printable without data loss, so that the file can be maintained and validated reliably.

Acceptance Criteria

1. THE Metric_Definitions_File SHALL be valid JSON that parses without error using JSON.parse()
2. FOR ALL entries in the Metric_Definitions_File, parsing the JSON then stringifying it then parsing it again SHALL produce an equivalent object (round-trip property)
3. THE Metric_Definitions_File SHALL contain a metric_id field in every entry that is a non-empty string
4. IF an optional field (exclusions, special_conditions, notes) has no value for a metric, THEN THE Metric_Definitions_File SHALL represent it as an empty string rather than omitting the key