Densities

AI implementation guide

How an AI agent should use Density

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.

When generating or modifying UI with UXDSL:

• Read the theme's spacing, densities, and breakpoints definitions before selecting spacing tokens.
• Prefer existing design-system tokens over introducing new values, tokens, or responsive rules.
• Prefer an appropriate density(n) token by default for component spacing.
• Use space(n) directly when a stable value across breakpoints is intentional. Use CSS directly when finer control outside the configured Density behavior is required.
• Do not replace Density with Spacing merely because their values match at one breakpoint. That would discard the intended responsive progression.
• If no Density token fits, inspect the theme and requested scope before creating a system-level token or choosing a deliberate local exception. Never reference an undefined token.
• Treat density(n) as a reference to a configured responsive spacing token. Never assume density(4) equals space(4) at every breakpoint.
• Reuse existing Density tokens when their configured progression matches the intended behavior.
• Do not reference undefined Density or Spacing tokens. When a new token is needed, define it in the theme before using it.
• Do not reproduce a Density mapping locally with explicit breakpoint rules when an existing Density token already represents the intended behavior.
• Change a Density mapping in the theme when the intended change should affect all consumers of that token.
• Use a local component rule when the behavior is an intentional exception that should not affect the Density token or its other consumers.
• Before creating a new Density token, check whether an existing token already provides the required responsive progression.
• Verify the result just below, at, and just above each configured breakpoint where those widths are valid, and check other components consuming the same Density token.

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.

Choose the token in the component. Define its responsive behavior in the theme.

Example

Given this example theme excerpt:

{
  "breakpoints": {
    "xs": 0,
    "md": 768,
    "xl": 1280
  },
  "spacing": {
    "4": "0.75rem",
    "5": "1rem",
    "6": "1.5rem"
  },
  "densities": {
    "4": "xs(space(4)) md(space(5)) xl(space(6))"
  }
}

When a component should follow that configured responsive progression, prefer:

.card {
  padding: density(4);
}

This resolves according to the theme:

• Below 768px → space(4) → 0.75rem.
• From 768px up to, but not including, 1280px → space(5) → 1rem.
• 1280px and above → space(6) → 1.5rem.

Avoid recreating the same system behavior locally:

.card {
  padding: xs(space(4)) md(space(5)) xl(space(6));
}

The local form duplicates behavior already represented by density(4) and disconnects the component from future changes to that Density mapping. It still references the spacing scale.

Explicit local responsive spacing is valid when the component intentionally requires behavior that should remain independent from the configured Density mapping.

Agent reasoning example

If asked:

Make this card's padding follow the application's responsive spacing.

The agent should:

1. Inspect the theme's available Density tokens.
2. Find an existing Density progression that matches the requested behavior.
3. Use that token in the component, for example padding: density(4).
4. Avoid generating local breakpoint rules that duplicate the token's progression.
5. Only create or modify a Density token when the requested behavior belongs at the design-system level.
6. Verify the resulting behavior around every configured breakpoint and check affected consumers when the Density mapping changes.

The component declares which responsive spacing token it uses.

The theme defines how that token behaves across breakpoints.