From harness-claude
Applies Gestalt proximity principle to group UI elements via spacing ratios (1:2+) and common regions. Useful for form fields, card layouts, navigation, dashboards, settings pages.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeThis skill uses the workspace's default tool permissions.
> Spatial grouping — elements near each other are perceived as related, controlling group membership through distance, with common region as a proximity amplifier
Applies Gestalt similarity principle to group UI elements by color, size, shape, texture for visual categorization in status indicators, navigation, tables, and component libraries.
Improves UI layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use for off-feeling layouts, crowded UIs, alignment issues, or poor composition.
Provides practical UI design patterns and principles from Refactoring UI and Practical UI for layout, spacing, typography, color, hierarchy, and styling in web projects.
Share bugs, ideas, or general feedback.
Spatial grouping — elements near each other are perceived as related, controlling group membership through distance, with common region as a proximity amplifier
Understand the law. The Gestalt principle of proximity states that elements placed close together are perceived as belonging to the same group, regardless of differences in shape, color, or size. Distance is the primary grouping mechanism in visual perception — it operates before color, before shape, before any other attribute. When a user looks at a layout, the first parse their visual system performs is spatial: what is near what?
Apply the proximity ratio. For any two elements that belong to the same group, the space between them must be noticeably less than the space between either element and the nearest element of a different group. The minimum effective ratio is 1:2 — intra-group spacing should be at most half the inter-group spacing. A 1:3 ratio is stronger and preferred when space allows.
Worked example — Stripe checkout form:
Decision procedure: List all element pairs. For each pair, decide: same group or different group? Assign intra-group spacing from your scale's lower values, inter-group spacing from higher values. Verify that no intra-group gap equals or exceeds any inter-group gap.
Use common region to amplify proximity. Common region — enclosing elements within a shared boundary (card, background color, border) — reinforces proximity. Elements inside the same container are perceived as more strongly grouped than elements that are merely close together without a boundary.
Worked example — Airbnb listing card:
When to add common region: When proximity alone is insufficient — typically when intra-group and inter-group spacing cannot achieve a 1:2 ratio due to layout constraints, or when elements are so numerous that spatial grouping alone creates visual noise.
Handle proximity conflicts. Sometimes the layout requires elements from different groups to be physically close. This happens in dense dashboards, multi-column forms, and responsive layouts where columns collapse. Resolution strategies:
border-bottom: 1px solid rgba(0,0,0,0.12) between list sections — the divider breaks the false proximity signal.background: #f6f9fc blocks alternating with white to separate groups that are vertically adjacent with only 16px between them.Calibrate proximity for different densities. The absolute pixel values change with context, but the ratio must be preserved:
| Context | Intra-group | Inter-group | Section gap | Ratio |
|---|---|---|---|---|
| Dense dashboard | 4-8px | 16-24px | 32-48px | 1:3:6 |
| Standard app UI | 8-12px | 24-32px | 48-64px | 1:3:6 |
| Marketing / landing | 16-24px | 48-64px | 80-128px | 1:3:5 |
Decision procedure: Pick your context density. Choose a base intra-group value from the table. Multiply by 3 for inter-group. Multiply by 5-6 for section gaps. Verify all values exist on your spacing scale (4px or 8px base).
Apply the isolation principle (inverse proximity). An element placed far from all other elements attracts attention through its isolation. This is proximity in reverse — the absence of nearby elements signals "this is special, different, or primary."
Worked example — Material Design FAB (Floating Action Button):
Worked example — Apple's "Buy" button on product pages:
Forms are the highest-stakes proximity challenge because users must understand which label belongs to which input, which inputs form a logical group, and where one section ends and another begins.
The label-to-input distance must always be tighter than the input-to-next-label distance. If both distances are equal, labels appear to float between two inputs and the association becomes ambiguous — the user must read the label text to figure out which input it describes, rather than seeing the relationship spatially.
Worked example — address form:
[Street Address] <- label
[________________] <- input } 4px label-to-input
} 24px input-to-next-label
[City] <- label
[________________] <- input } 4px label-to-input
} 24px input-to-next-label
[State] [Zip Code] <- labels (inline group)
[______] [______] <- inputs } 4px label-to-input
} 48px to next section
[Payment Information] <- section heading
The 4px : 24px : 48px cascade makes group membership unambiguous. A user scanning vertically sees three distinct clusters (street, city, state/zip) within a larger "address" section, all separated from "payment" by a 48px gap.
Navigation menus use proximity to signal hierarchy:
When a multi-column layout collapses to single-column on mobile, previously side-by-side groups become vertically stacked. This can create false proximity — a group's last element becomes adjacent to the next group's first element with the same spacing that exists within groups.
Fix: Increase inter-group spacing by at least one step on your scale when collapsing to single column. If desktop uses 24px between groups, mobile should use 32px or 40px to compensate for the lost column separation.
Equidistant spacing. Applying the same gap (e.g., gap: 16px) to every element regardless of group membership. This is the most common proximity violation. The layout becomes a flat list where nothing is grouped — labels float ambiguously, form sections bleed into each other, and navigation items all appear equally related. Fix: differentiate intra-group and inter-group spacing by at least a 1:2 ratio.
Label proximity inversion. Placing a label equidistant between two inputs (or closer to the wrong input). In a vertical form with 16px between a label and the input below it, and 16px between that input and the next label, the labels are perceptually unanchored. Reduce label-to-own-input spacing to 4-8px while keeping input-to-next-label spacing at 16-24px.
Over-boxing (common region abuse). Wrapping every small group in a card or bordered container when proximity alone would suffice. This creates visual noise — borders compete with content for attention, the page looks like a spreadsheet, and the hierarchy flattens. Use common region only when proximity ratios cannot achieve clear grouping (dense layouts, overlapping groups, mobile collapses).
Proximity without hierarchy. Grouping elements correctly by distance but failing to establish which group is primary. All groups are equally spaced from the viewport edges, equally sized, equally prominent. Proximity creates groups but does not rank them — combine with visual hierarchy (size, color, position) to indicate importance.
Stripe's Payment Form:
Apple iOS Notification Grouping:
Material Design List Sections:
56px row height and internal padding)16px gap plus a subheader label in 14px muted textAirbnb Search Filters: