UX-DSL
UX-DSL/docs/surfaces
XS0px

Surfaces

Background layers, cards, and elevation styles.

Surfaces are intelligent, composite containers that manage background, border, shadow, and spacing. They use a flexible "Smart Mixin" syntax to apply responsive defaults while allowing granular control over density, radius, and depth.

.card { @ds-surface(contained) }

Interactive Playground

Interactive Surface
Adjust controls to see how parameters affect the surface.
.my-element {
  @ds-surface(contained primary density(2) radius(2) shadow(1));
}

Resolved CSS Output for .my-element

.my-element {
  background-color: palette(primary-main);
  color: palette(primary-contrast);
  padding: density(2);
  border-radius: radius(2);
  border: none;
  box-shadow: shadow(1);
}

Mixin Documentation

The @ds-surface mixin is the primary primitive for building containers. It accepts a Variant (structure) and Tone (color), followed by optional granular tokens for Density (padding), Radius, and Shadow.

Smart Parameters:
  • variant: Base style (contained, outlined, flat). Determines default borders/shadows.
  • tone: Applies semantic color palette (bg/text/border) automatically.
  • density(N): Sets responsive padding. Scales automatically across breakpoints.
  • radius(N): Sets border-radius. Defaults to system standard (usually 2).
  • shadow(N): Sets box-shadow depth. Defaults based on variant (1 for contained, 0 for others).

Stacking Context Visualization

flatsurface(flat)
outlinedsurface(outlined)
containedsurface(contained)

Token Reference

surface(contained)
High emphasis surface with shadow and background color. Used for cards, modals, and floating elements.
Preview Content
padding:density(2)
radius:radius(2)
bg:palette(surface-main)
color:palette(surface-contrast)
border:1px solid palette(surface-dark)
shadow:shadow(1)
surface(outlined)
Medium emphasis surface with border and transparent background. Used for secondary cards and bordered sections.
Preview Content
padding:density(2)
radius:radius(2)
bg:transparent
color:palette(surface-contrast)
border:1px solid palette(neutral-main)
shadow:none
surface(flat)
Low emphasis surface with no border or shadow. Used for simple containers or transparent wrappers.
Preview Content
padding:density(2)
radius:radius(2)
bg:transparent
color:palette(surface-contrast)
border:none
shadow:none