CORE UTILITY FAMILY

Spacing

Apply physical and logical padding, margin, gaps, sibling spacing, scroll margin, and scroll padding from the shared spacing scale.

completeTarget v0.25 verified examplesRegistry JSON ↗

WHEN TO USE IT

Choose the right tool for the layout.

Prefer gap for flex and grid children, space utilities for ordinary sibling flow, and logical ps/pe/pbs/pbe or ms/me/mbs/mbe utilities when direction-aware writing modes are required.

QUICK REFERENCE

Classes and generated CSS

These examples are resolved by the compiler when the registry manifest is generated. A broken example fails the test suite.

ClassGenerated declarations and keyframes

co-pbs-4padding-block-start: calc(var(--co-space-unit) * 4);

-co-mbe-2margin-block-end: calc(calc(var(--co-space-unit) * 2) * -1);

co-gap-x-6column-gap: calc(var(--co-space-unit) * 6);

co-space-x-reverse--co-space-x-reverse: 1;

co-scroll-pbe-(--offset)scroll-padding-block-end: var(--offset);

VISUAL EXAMPLE · PADDING

Create space inside a surface

Padding separates content from its own border. Use axis utilities when horizontal and vertical rhythm need different values.

co-px-6 co-py-4

The gray area represents internal padding.

component.coord

<article class="co-px-6 co-py-4 co-border">
  <h3>Card title</h3>
  <p>Content stays away from the border.</p>
</article>

VISUAL EXAMPLE · MARGIN

Separate neighboring components

Margin creates space outside an element. Keep vertical component rhythm explicit by placing the margin on the element that owns the separation.

Account

co-mt-2

component.coord

<section>
  <h2>Account</h2>
  <p class="co-mt-2">Manage your profile and preferences.</p>
  <button class="co-mt-6">Save changes</button>
</section>

VISUAL EXAMPLE · GAP

Space grid and flex children evenly

Gap belongs to the container and remains predictable when items wrap or the track count changes. Axis-specific gaps let rows and columns use different rhythm.

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

component.coord

<section class="co-grid co-grid-cols-3 co-gap-x-3 co-gap-y-6">
  <article>One</article>
  <article>Two</article>
  <article>Three</article>
  <article>Four</article>
  <article>Five</article>
  <article>Six</article>
</section>

VISUAL EXAMPLE · SIBLING SPACING

Apply rhythm between direct children

Space utilities insert separation between siblings without adding extra space before the first or after the last item.

Profile

Notifications

Security

component.coord

<ul class="co-space-y-3">
  <li>Profile</li>
  <li>Notifications</li>
  <li>Security</li>
</ul>

VISUAL EXAMPLE · LOGICAL SPACING

Let spacing follow writing direction

Logical padding and margin use inline start, inline end, block start, and block end instead of hard-coding physical sides.

Englishco-ps-6

العربيةco-ps-6

component.coord

<article dir="ltr" class="co-ps-6 co-pe-3 co-border-s-2">English</article>
<article dir="rtl" class="co-ps-6 co-pe-3 co-border-s-2">العربية</article>

BASIC USAGE

Apply a utility directly.

Keep the complete class string in your template so the plain-text scanner can discover it without evaluating application code.

component.coord

<div class="co-pbs-4 -co-mbe-2 co-gap-x-6 co-space-x-reverse co-scroll-pbe-(--offset)">
  Your content
</div>

HOW IT WORKS

Core concepts

01
Numeric values multiply --co-space-unit, which defaults to 0.25rem.
02
Fractions resolve to percentages and px resolves to one CSS pixel.
03
Logical start/end utilities adapt to direction while block-start/block-end adapt to writing mode.
04
Sibling space utilities target every direct child except the last and include explicit reverse-axis controls.
05
Scroll spacing mirrors physical and logical padding/margin edges.

CSS PROPERTIES

What this family controls

paddingpadding-inlinepadding-blockmarginmargin-inlinemargin-blockgapscroll-marginscroll-padding

VARIANTS

Responsive and state conditions

Prefix any supported utility with responsive or state variants. Variants compose from left to right and the compiler emits the required selector or at-rule.

component.coord

<div class="co-pbs-4 md:-co-mbe-2 hover:co-pbs-4">
  Responsive and state-aware content
</div>

ARBITRARY VALUES

Escape the scale when necessary

Use square brackets for a one-off CSS value. Prefer theme tokens for values repeated across components so an AI agent and human reviewer can recognize design intent.

Arbitrary syntax

co-p*
co-[content-visibility:auto]

NEGATIVE VALUES

Reverse supported values

Place the minus sign before the framework prefix. Only properties where negative CSS values are meaningful accept this modifier.

Canonical negative syntax

-co-{utility}
-co-mbe-2

SCOPE BOUNDARIES

Intentional boundaries

This family is implemented, documented, and tested. These notes define where a neighboring family or browser behavior takes over.

Negative values are intentionally valid for margin, scroll margin, and sibling spacing—not padding, gap, or scroll padding.
Position offsets are documented in Layout even though they share the same value resolver.
Dynamically concatenated spacing classes cannot be detected by the scanner.

Previous← Flexbox and grid NextSizing →