Building a Consistent Spacing Scale for Reusable UI Cards

Requirements

The goal is to unify spacing for title, status, duration, and log-entry links across code-inspection and unit-test stage cards so that identical content relationships use identical distances.

Initial Implementation

The first version set padding and margins independently for each card type. Title-to-status gaps were 7px and 19px respectively; status-to-action distances also differed.

Figure 1: Two stage cards with independently set content spacing.

Problem Analysis

Major Issues

Although the cards share the same structure, the distances between title and status and between status and log entry differ. This creates inconsistent visual density and forces maintainers to calibrate each card separately.

The key is to unify the same type of content relationship , not to make every distance in the card identical.

Design Principles

Predefine a small set of spacing tiers to eliminate arbitrary tweaks. Tiers must be perceptibly different: small scales are tighter, large scales more open. For example, 12 to 16 is a ~33% jump, while 500 to 520 is only 4%. The same pixel delta has different perceptual impact at different scales, so simply mandating multiples of a base unit can still leave many near-duplicate options.

Optimization Implementation

Spacing Roles

Assign distinct tiers to three roles: title-to-status (12px), content-to-action (24px), and card-to-card gap (16px). Card padding is set to 24px. The exact numbers matter less than the rule that the same relationship reuses the same token, preserving intra-group and inter-group distinction.

CSS Implementation

.stage-grid { gap: 16px; }
.stage-card { padding: 24px; }
.stage-card h3 { margin: 0 0 12px; }
.stage-card p { margin: 0 0 24px; }

Apply these rules to all similar stage cards and avoid overriding with near-identical values on a per-card basis. In production, express the roles via shared design tokens.

Content Adaptation

Test with two-line stage names, longer status text, and varied log-entry links. Verify that natural height changes do not break grouping clarity. If action areas need alignment, handle it through layout (e.g., flexbox) rather than inserting custom whitespace per card.

Acceptance Verification

Figure 2: Same-type cards now share identical content-spacing rules.

Compare the two versions to confirm spatial consistency across repeated content; cross-check the stylesheet to ensure tokens are actually shared.

☐ Title-to-status and content-to-action distances are consistent across same-type cards.

☐ Intra-group, inter-group, and card-to-card distinctions remain clear.

☐ Under long stage names, content does not overlap and action ownership stays obvious.

Application Exercise

Unify spacing for code-inspection, unit-test, and image-build stage cards. Deliberately include a two-line stage name. Deliver a component sketch and a spacing-role table documenting which tier serves which relationship and how long content extends naturally.