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); }
Navigation
.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); }