Skip to content

ADR-010: KPI Card Styling Alignment with Vizro Best Practices

Note: This ADR was originally numbered ADR-001 but was renumbered to ADR-010 during the 2026-01-28 namespace consolidation to resolve collision with ADR-001-cost-metric-selection.md

Status: Accepted
Date: 2026-01-28
Deciders: @cloud-architect, @product-owner

Context

The ITSM dashboard currently uses compact KPI cards (120px height) implemented in Sprint 24. Manager feedback requests KPI styling aligned with Vizro best practices for better visual clarity and responsive design (25%-200% zoom support).

Key Constraints: 1. Vizro's kpi_card() function has no height parameter (unlike vm.Graph) 2. KPI dimensions controlled exclusively via CSS .card-kpi class 3. Must maintain responsive layout across 25%-200% browser zoom 4. Reference implementations available: kpi-dashboard (150px), call-center (implicit ~120px)

Decision

Adopt kpi-dashboard CSS pattern with 150px height for KPI cards.

Implementation

Update /dashboards/itsm/src/assets/custom.css:

/* Sprint 26 (R2): Vizro best practice KPI dimensions */
.card-kpi {
    min-width: 260px;      /* Increased from 240px for better text layout */
    padding: 0.75rem;      /* Match kpi-dashboard pattern */
    height: 150px;         /* Vizro best practice (kpi-dashboard proven) */
}

/* KPI container gap for responsive layout */
.kpi-container {
    gap: 20px;  /* Match call-center col_gap='20px' pattern */
}

Rationale

Option Height Padding Pros Cons Decision
Current (Sprint 24) 120px 0.5rem Compact, fits more data Icon/text cramped at 150%+ zoom ❌ Rejected
kpi-dashboard pattern 150px 0.75rem Proven responsive 25%-200%, better icon/text balance Slightly taller cards ✅ SELECTED
call-center pattern ~120px (implicit) N/A Works for 5-KPI layout No explicit CSS (harder to maintain) ❌ Rejected

Consequences

Positive

  • Proven Pattern: kpi-dashboard already validated 150px height across zoom levels
  • Better Readability: More breathing room for icon + value + reference text
  • Consistent Gap: 20px spacing matches call-center visual rhythm
  • Accessibility: WCAG 2.1 AA compliance easier with larger touch targets

Negative

  • Vertical Space: KPI row increases from ~140px to ~170px total height
  • Mitigation: vm.Flex layout auto-adjusts, no fixed grid ratios (Sprint 25A)
  • Existing Screenshots Invalid: Visual regression tests need new baselines
  • Mitigation: Playwright auto-screenshot update in E2E tests

Risks

Risk Probability Impact Mitigation
Cards overflow at 25% zoom LOW MEDIUM Tested kpi-dashboard pattern already handles this
Text truncation at 200% zoom LOW LOW 0.75rem padding + 150px height provides buffer

Alternatives Considered

  1. Keep 120px height + increase padding - Rejected: Causes text overflow at 150%+ zoom (tested in Sprint 24)

  2. Dynamic height via JavaScript - Rejected: Anti-pattern for Vizro (CSS should handle responsive design)

  3. Different heights per KPI - Rejected: Inconsistent UX violates Requirement R5 (Consistent UX/UI)

References

  • kpi-dashboard CSS: /dashboards/kpi-dashboard/assets/css/custom.css (line 6-9)
  • call-center layout: /dashboards/call-center/app.py (line 44-98)
  • Vizro kpi_card docs: Native component with no height parameter
  • Sprint 24 implementation: 120px compact height (previous iteration)

Evidence

  • CSS diff: tmp/cloud-infrastructure/architecture-decisions/file-modification-map.json
  • Visual regression: tmp/cloud-infrastructure/test-results/kpi-styling-screenshots/
  • E2E validation: Playwright test at 5 zoom levels (25%, 50%, 100%, 150%, 200%)

Version: 1.0
Next Review: Post-Sprint 26 retrospective
Supersedes: Sprint 24 compact KPI design (120px height)