SGDS Spacing Utilities Skill

Helps developers use SGDS spacing utilities (margin, padding, gap) based on the 4px scale system.

Prerequisites

Required: Complete setup from sgds-utilities-setup skill first.

Spacing utilities require the utility CSS import but do NOT require theme files.

Core Concept

Base Unit: Every spacing value = multiplier × 4px

All SGDS spacing utilities use the sgds: prefix (Tailwind v4 @theme syntax).

Always prefer semantic spacing utilities over raw numeric utilities. SGDS provides purpose-named spacing tokens defined in responsive.css — they adapt across breakpoints and encode design intent. Only fall back to raw numeric utilities (sgds:p-4, sgds:gap-6, sgds:mb-3, etc.) when no semantic token fits.

Semantic Spacing Utilities (Always Prefer These)

All semantic tokens are responsive — their values change at mobile, tablet (≥1024px), and desktop (≥1440px) breakpoints.

Text Gap — spacing between text/content elements

Use for gaps between paragraphs, headings, and inline text groups.

Class	Tokens
sgds:gap-text-2-xs	--sgds-text-gap-2-xs
sgds:gap-text-xs	--sgds-text-gap-xs
sgds:gap-text-sm	--sgds-text-gap-sm
sgds:gap-text-md	--sgds-text-gap-md
sgds:gap-text-lg	--sgds-text-gap-lg
sgds:gap-text-xl	--sgds-text-gap-xl
sgds:gap-text-2-xl	--sgds-text-gap-2-xl

Layout Gap — spacing between layout sections

Use for gaps between page sections, grid columns, and layout areas.

Class	Token
sgds:gap-layout-2-xs	--sgds-layout-gap-2-xs
sgds:gap-layout-xs	--sgds-layout-gap-xs
sgds:gap-layout-sm	--sgds-layout-gap-sm
sgds:gap-layout-md	--sgds-layout-gap-md
sgds:gap-layout-lg	--sgds-layout-gap-lg
sgds:gap-layout-xl	--sgds-layout-gap-xl

Layout Padding — padding for layout/page areas

Use for section padding, page padding, and container insets. Supports sgds:p-layout-*, sgds:px-layout-*, and sgds:py-layout-*.

Class	Token
sgds:p-layout-xs	--sgds-layout-padding-xs
sgds:p-layout-sm	--sgds-layout-padding-sm
sgds:p-layout-md	--sgds-layout-padding-md
sgds:p-layout-lg	--sgds-layout-padding-lg
sgds:p-layout-xl	--sgds-layout-padding-xl

Component Gap — spacing inside custom components

Use for gaps between internal elements when building a custom component.

Class	Token
sgds:gap-component-xs	--sgds-component-gap-xs
sgds:gap-component-sm	--sgds-component-gap-sm
sgds:gap-component-md	--sgds-component-gap-md
sgds:gap-component-lg	--sgds-component-gap-lg
sgds:gap-component-xl	--sgds-component-gap-xl

Component Padding — padding inside custom components

Use for internal padding when building a custom component. Supports sgds:p-component-*, sgds:px-component-*, and sgds:py-component-*.

Class	Token
sgds:p-component-xs	--sgds-component-padding-xs
sgds:p-component-sm	--sgds-component-padding-sm
sgds:p-component-md	--sgds-component-padding-md
sgds:p-component-lg	--sgds-component-padding-lg
sgds:p-component-xl	--sgds-component-padding-xl

Container Width

Use sgds:w-container for the standard responsive container width. It maps to --sgds-container-width which changes from 360px (mobile) → 888px (tablet) → 1312px (desktop).

<div class="sgds:mx-auto sgds:w-container">
  <!-- responsive-width page container -->
</div>

---

Raw Numeric Utilities (Fallback Only)

Only use raw multiplier-based utilities when no semantic token above fits the use case. Base unit: n × 4px.

• sgds:p-{n} / sgds:px-{n} / sgds:py-{n} / sgds:pt/pr/pb/pl-{n} — padding
• sgds:m-{n} / sgds:mx-{n} / sgds:my-{n} / sgds:mt/mr/mb/ml-{n} — margin
• sgds:mx-auto — horizontal centering
• sgds:gap-{n} / sgds:gap-x-{n} / sgds:gap-y-{n} — flex/grid gap
• Negative: sgds:-mt-{n}, sgds:-ml-{n}, etc.

Common Use Cases

Page Layout (layout gap + layout padding + container width)

<!-- Responsive container with layout-appropriate padding -->
<div class="sgds:mx-auto sgds:w-container sgds:px-layout-md">
  <!-- Sections separated by layout gap -->
  <div class="sgds:flex sgds:flex-col sgds:gap-layout-lg">
    <section>
      <h2>Section Title</h2>
      <!-- Text elements separated by text gap -->
      <div class="sgds:flex sgds:flex-col sgds:gap-text-md">
        <p>Paragraph 1</p>
        <p>Paragraph 2</p>
      </div>
    </section>
    <section>
      <h2>Another Section</h2>
    </section>
  </div>
</div>

Custom Card Component (component gap + component padding)

<div class="sgds:bg-surface-raised sgds:p-component-md sgds:rounded-md">
  <div class="sgds:flex sgds:flex-col sgds:gap-component-sm">
    <h3>Card Title</h3>
    <p>Card description text</p>
    <button class="sgds:p-component-xs">Action</button>
  </div>
</div>

Custom Form Component (component gap + component padding)

<form class="sgds:flex sgds:flex-col sgds:gap-component-md">
  <div class="sgds:flex sgds:flex-col sgds:gap-text-xs">
    <label>Name</label>
    <input class="sgds:p-component-xs">
  </div>
  <div class="sgds:flex sgds:flex-col sgds:gap-text-xs">
    <label>Email</label>
    <input class="sgds:p-component-xs">
  </div>
  <button class="sgds:px-component-sm sgds:py-component-xs">Submit</button>
</form>

Grid Layout (layout gap)

<div class="sgds:grid sgds:grid-cols-3 sgds:gap-layout-md sgds:p-layout-md">
  <div class="sgds:p-component-sm">Item 1</div>
  <div class="sgds:p-component-sm">Item 2</div>
  <div class="sgds:p-component-sm">Item 3</div>
</div>

Text Content Block (text gap)

<article class="sgds:flex sgds:flex-col sgds:gap-text-lg">
  <h1>Article Title</h1>
  <p class="sgds:flex sgds:flex-col sgds:gap-text-sm">Lead paragraph</p>
  <p>Body paragraph 1</p>
  <p>Body paragraph 2</p>
</article>

---

For AI Agents: Always prefer semantic spacing utilities over raw numeric ones. Decision guide: text between text elements → sgds:gap-text-*; spacing between layout sections or grid areas → sgds:gap-layout-*; padding on page/section areas → sgds:p-layout-* / sgds:px-layout-* / sgds:py-layout-*; building a custom component (gap inside) → sgds:gap-component-*; building a custom component (padding inside) → sgds:p-component-* / sgds:px-component-* / sgds:py-component-*; responsive container width → sgds:w-container. Only use raw numeric utilities (sgds:p-4, sgds:gap-6, sgds:mb-3, etc.) when no semantic token fits the context. All semantic tokens are responsive — they adapt across mobile, tablet, and desktop breakpoints.