Spacing

Define spacing once. Update every consumer from your theme.

One spacing scale. Consistent decisions everywhere.

UXDSL builds on standard CSS. Spacing defines the base spacing values, and Density makes that spacing responsive. Prefer Density for component spacing, use Spacing when a stable value is intentional, and use CSS directly when finer control is needed. This is the recommended authoring approach, not a compiler restriction.

Spacing tokens are named entries in your theme’s spacing scale. Use them for padding inside a box, margins around it, and gaps between items. Components choose a token; the theme supplies its value.

space(4) references entry 4. It does not mean four pixels or four times a base unit. The theme defines the measurement.

1. Define the scale in your theme JSON

This reference excerpt defines three reusable values:

{
  "spacing": {
    "2": "0.25rem",
    "4": "0.75rem",
    "6": "1.5rem"
  }
}

2. Use Spacing directly when stable spacing is intentional

In this example, the card padding and actions gap intentionally keep the same spacing value across breakpoints. For ordinary component spacing, prefer an appropriate Density token.

UXDSL you write

.card, .panel {
  padding: space(4);
}

.actions {
  display: flex;
  gap: space(4);
}

Equivalent plain CSS

:root {
  --uxdsl__space__2: 0.25rem;
  --uxdsl__space__4: 0.75rem;
  --uxdsl__space__6: 1.5rem;
}

.card, .panel {
  padding: var(--uxdsl__space__4);
}

.actions {
  display: flex;
  gap: var(--uxdsl__space__4);
}

Plain CSS custom properties can provide the same reuse. UXDSL expresses those references through the theme’s token vocabulary. The benefit is maintaining shared values instead of repeating measurements throughout the application.

3. Update the value once

Change spacing entry 4 from 0.75rem to 1rem. When the updated theme is compiled or applied through the runtime, every consumer of space(4) receives that value without changing its declaration. This includes Density rules wherever they resolve to space(4).

Density by default, Spacing for deliberate control

Start with an appropriate density(n) token for component spacing. Use space(n) directly when a stable spacing value is intentional. Direct Spacing still belongs to the design system; it bypasses the Density progression. Matching token numbers or matching values at one breakpoint do not make the two interchangeable.

Stable across breakpoints does not mean permanently fixed: space() does not add responsive rules itself. Its result still follows the theme value, CSS units and any deliberate overrides. For example, rem follows the root font size; a configured clamp() can vary with the viewport.

For shared responsive spacing, see Density. Keep explicit local responsive rules for intentional component exceptions.

Edit a shared spacing token and see its consumers update together.

Try it: one token, two paddings and a gap

This demonstration uses direct Spacing to show the base scale: these paddings and gaps intentionally keep a stable value across breakpoints. Prefer Density when building ordinary component spacing.

The colored areas below use the page’s actual CSS variables. Edit space(4) to update both boxes and the gap between the action items.

Card: padding: space(4)

Content

Panel: padding: space(4)

Content

Actions: gap: space(4)

FirstSecond

These edits update the playground’s custom theme and persist spacing overrides in this browser when storage is available. Other UI using the token may also change. They do not write to your source JSON file. The reference examples above stay unchanged.

Concentric Spacing Visualization

Each ring shows a spacing level measured from the same content. These are alternative distances, not nested paddings added together. Click a ring to edit its token, or use the labeled token fields below. Custom values determine ring size; token numbers alone do not guarantee size order.

Visible Rings:4

Content

space(1)

space(2)

space(3)

space(4)

SpacingUsage.uxdsl

.any-class {
  padding: space(4);
}

Global Spacing Tokens

Update the tokens below to reflect changes in the UI.

space(1)

space(2)

space(3)

space(4)

space(5)

space(6)

space(7)

space(8)

space(9)

space(10)

space(11)

space(12)

space(13)

space(14)

space(15)

space(16)

AI implementation guide

How an AI agent should use Spacing

When generating or modifying UI with UXDSL:

Inspect the active theme’s spacing definitions and existing component conventions before selecting tokens. Read densities and breakpoints when responsive behavior is required.
Treat space(n) as a configured token reference, not a pixel count or arithmetic multiplier. Do not infer values from another framework’s scale.
Prefer an existing token that matches the intended spacing. Do not reference undefined tokens; define a new token in the theme before using it when a system-level addition is needed.
Prefer an appropriate density(n) token for component spacing. Use space(n) directly when a stable value is intentional, and use CSS directly when finer control is required. Do not duplicate an existing Density progression locally.
Do not choose space(n) merely because it matches a Density token at the current breakpoint. Preserve the component’s intended responsive behavior.
If no Density token fits, inspect the theme and the requested scope before defining a system-level token or using a deliberate local exception. Never invent an undefined reference.
Choose padding for internal space, margin for external separation, and gap for spacing between items in a compatible layout.
Change a shared spacing value only when the intended change should affect all its consumers. Inspect direct references and Density mappings that depend on it.
For a local adjustment, select another appropriate token in the component. Use a deliberate local exception when the design requires behavior independent of shared tokens.
Edit source theme definitions or use the supported runtime API. Do not hand-edit generated CSS as the source of truth.
Account for the configured units. A stable rem value can have a different pixel size when the root font size changes; space() itself does not create breakpoint rules.
Verify affected padding, margins and gaps, check shared consumers for overflow or wrapping, and test relevant themes. If Density references the edited token, also check its breakpoint boundaries.

Decision rule: Prefer Density for component spacing. Use Spacing for intentional stable values and CSS for finer control. Change shared Spacing or Density definitions only for intentional system-level changes.

Example

Given this theme excerpt:

{
  "spacing": {
    "2": "0.25rem",
    "4": "0.75rem",
    "6": "1.5rem"
  }
}

For this deliberate exception, the card padding and actions gap must remain stable across breakpoints. Reuse the configured Spacing value:

.card {
  padding: space(4);
}
.actions {
  display: flex;
  gap: space(4);
}

Both references resolve to 0.75rem. Avoid replacing them with a hardcoded 0.75rem when they should remain connected to the theme.

Agent reasoning example

Make only this card’s padding smaller, and intentionally keep it stable across breakpoints using the application’s spacing scale.

Inspect the card’s current token and the actual spacing values in the theme.
Choose an appropriate smaller existing value; in this example, space(2) is smaller than space(4).
Change the card to padding: space(2). Keep the shared value of spacing entry 4 intact because the request applies only to the card.
Check the card’s content, wrapping and overflow, and confirm that the actions gap remains unchanged.

If the request instead changes spacing entry 4 across the system, update its theme value, apply or compile the theme, and verify both direct consumers and dependent Density mappings.

Choose the token in the component. Define its value in the theme.