What is ux-spacing-layout?

This Claude skill implements a sophisticated fluid spacing system based on Utopia principles and container query units (cqi). It empowers developers to create responsive, harmonious web layouts by providing a standardized set of spacing tokens and layout patterns that automatically interpolate between screen sizes, ensuring perfect visual rhythm and eliminating the need for manual breakpoint management.

When should I use ux-spacing-layout?

ux-spacing-layout is useful in the following scenarios: • Case 1: Implementing fluid padding and margins for web components to ensure they scale gracefully from mobile to desktop views. • Case 2: Creating flexible layout structures using u-stack and u-row utilities to maintain consistent gaps between elements in complex UIs. • Case 3: Developing container-aware components that adjust their internal spacing based on their parent container's width using cqi units. • Case 4: Enforcing a unified design system across a project by utilizing predefined space scales and one-up pairs for asymmetric spacing relationships.

name	ux-spacing-layout
description	Utopia fluid spacing tokens and layout patterns. Use when applying margins, padding, gaps, or creating layouts. Covers space scale, container widths, and responsive spacing. (project)

UX Spacing & Layout Skill

Fluid spacing system using Utopia scale with container query inline (cqi) units. This skill covers spacing tokens, layout patterns, and visual rhythm.

Space Scale

The project uses Utopia fluid spacing with cqi units. Sizes interpolate based on container width.

IMPORTANT: cqi units require container-type: inline-size on an ancestor.

Space Tokens

Token	Min (320px)	Max (1240px)	Usage
`--space-3xs`	4px	6px	Hairline gaps
`--space-2xs`	8px	11px	Tight spacing
`--space-xs`	12px	17px	Compact gaps
`--space-s`	16px	22px	Standard small
`--space-m`	24px	33px	Standard medium
`--space-l`	32px	44px	Generous spacing
`--space-xl`	48px	67px	Section breaks
`--space-2xl`	64px	89px	Major sections
`--space-3xl`	96px	133px	Page-level gaps

One-Up Pairs

For asymmetric spacing relationships:

Token	Values	Usage
`--space-3xs-2xs`	4px → 11px	Micro to tight
`--space-2xs-xs`	8px → 17px	Tight to compact
`--space-xs-s`	12px → 22px	Compact to standard
`--space-s-m`	16px → 33px	Standard progression
`--space-m-l`	24px → 44px	Medium to generous
`--space-l-xl`	32px → 67px	Section transitions

Usage Patterns

Padding

/* Compact element */
.chip {
  padding: var(--space-2xs) var(--space-xs);
}

/* Standard button */
.button {
  padding: var(--space-s) var(--space-m);
}

/* Card */
.card {
  padding: var(--space-m);
}

/* Modal */
.modal {
  padding: var(--space-l);
}

Margins

/* Between inline elements */
.inline-group > * + * {
  margin-inline-start: var(--space-xs);
}

/* Between sections */
section + section {
  margin-block-start: var(--space-xl);
}

/* Page container */
.page {
  margin-inline: auto;
  padding-inline: var(--space-m);
}

Gap (Flexbox/Grid)

/* Tight list */
.list-tight {
  display: flex;
  flex-direction: column;
  gap: var(--space-2xs);
}

/* Standard stack */
.stack {
  display: flex;
  flex-direction: column;
  gap: var(--space-s);
}

/* Card grid */
.grid {
  display: grid;
  gap: var(--space-m);
}

/* Icon + text */
.icon-text {
  display: flex;
  align-items: center;
  gap: var(--space-xs);
}

Layout Utilities

u-stack (Vertical)

u-stack[gap="3xs"] { gap: var(--space-3xs); }
u-stack[gap="2xs"] { gap: var(--space-2xs); }
u-stack[gap="xs"]  { gap: var(--space-xs); }
u-stack[gap="s"]   { gap: var(--space-s); }
u-stack[gap="m"]   { gap: var(--space-m); }
u-stack[gap="l"]   { gap: var(--space-l); }
u-stack[gap="xl"]  { gap: var(--space-xl); }

u-row (Horizontal)

u-row[gap="xs"]  { gap: var(--space-xs); }
u-row[gap="s"]   { gap: var(--space-s); }
u-row[gap="m"]   { gap: var(--space-m); }

Container Widths

.u-container {
  width: min(100% - var(--space-m) * 2, var(--max-width, 1200px));
  margin-inline: auto;
}

.narrow { --max-width: 600px; }
.medium { --max-width: 900px; }
.wide   { --max-width: 1200px; }

Visual Rhythm

Consistent Spacing Rules

Related items: Use --space-2xs to --space-xs
Grouped elements: Use --space-s to --space-m
Sections: Use --space-l to --space-xl
Page breaks: Use --space-2xl to --space-3xl

Example Component

.card {
  /* Card padding */
  padding: var(--space-m);

  /* Internal spacing */
  display: flex;
  flex-direction: column;
  gap: var(--space-s);
}

.card-header {
  display: flex;
  align-items: center;
  gap: var(--space-xs);
}

.card-content {
  /* Paragraph spacing */
  display: flex;
  flex-direction: column;
  gap: var(--space-2xs);
}

.card-actions {
  /* Button group */
  display: flex;
  gap: var(--space-xs);
  margin-block-start: var(--space-s);
}

Responsive Spacing

Container Queries

/* Compact on small containers */
@container (max-width: 400px) {
  .card {
    padding: var(--space-s);
    gap: var(--space-xs);
  }
}

/* Generous on large containers */
@container (min-width: 800px) {
  .card {
    padding: var(--space-l);
    gap: var(--space-m);
  }
}

Asymmetric Spacing

Use one-up pairs for progressive spacing:

.section {
  /* Tight top, generous bottom */
  padding-block: var(--space-s-m) var(--space-m-l);
}

Common Patterns

Form Layout

.form {
  display: flex;
  flex-direction: column;
  gap: var(--space-m);
}

.form-field {
  display: flex;
  flex-direction: column;
  gap: var(--space-2xs);
}

.form-actions {
  display: flex;
  gap: var(--space-s);
  margin-block-start: var(--space-s);
}

.nav {
  display: flex;
  gap: var(--space-xs);
  padding: var(--space-2xs);
}

.nav-item {
  padding: var(--space-2xs) var(--space-s);
}

Dialog/Modal

.modal {
  padding: var(--space-l);
}

.modal-header {
  padding-block-end: var(--space-m);
  border-block-end: 1px solid var(--theme-outline);
}

.modal-body {
  padding-block: var(--space-m);
}

.modal-footer {
  padding-block-start: var(--space-m);
  display: flex;
  justify-content: flex-end;
  gap: var(--space-s);
}

Avoid

/* DON'T: Fixed pixel values */
.bad {
  padding: 16px;
  margin: 24px;
}

/* DON'T: Magic numbers */
.bad {
  gap: 13px;
}

/* DON'T: Inconsistent spacing */
.bad {
  padding: 10px 20px 15px 25px;
}

Do

/* DO: Use space tokens */
.good {
  padding: var(--space-s);
  margin: var(--space-m);
}

/* DO: Consistent relationships */
.good {
  padding: var(--space-s) var(--space-m);
}

ux-spacing-layout

When & Why to Use This Skill

Use Cases