Utilities, Mixins & Functions

USWDS provides three complementary approaches for applying design tokens and styles: utility classes in HTML, Sass mixins for component stylesheets, and Sass functions for computed values. Each serves a different purpose and can be used together.

Note: The information on this page is here for your reference. In order to maintain consistency, please consult with your Design System Manager before making application level customizations.

Overview

• Utility classes — Precompiled, single-purpose CSS classes applied directly in HTML (e.g. .bg-primary, .shadow-3, .margin-x-2). They require no Sass compilation at the point of use.
• Mixins — Reusable Sass blocks included with @include that output one or more CSS declarations. They accept parameters and bundle multiple properties into a semantic class name.
• Functions — Sass functions that return a single value (a color, length, or token) for use inside properties or variables. They do not emit CSS by themselves.

Utility Classes

Utility classes are the primary way to apply USWDS design tokens in markup. Each class maps to a single CSS property and value, making them predictable and easy to scan.

Usage

Apply utility classes directly to HTML elements:

<div class="bg-white padding-3 shadow-3 border-1px border-base-lighter">
  <p class="font-sans-md text-bold margin-bottom-1">Card title</p>
  <p class="font-sans-xs text-base">Card description text.</p>
</div>

Strengths

• Fast prototyping — no Sass build step needed for styling changes
• Predictable — each class does exactly one thing
• Responsive variants available (e.g. .desktop:margin-x-4)

Considerations

• Verbose markup when many classes are applied to a single element
• Not easily parameterized — you choose from the available token values

Sass Mixins

Mixins let you bundle multiple CSS declarations behind a semantic name. Use them when building reusable component styles that combine several design tokens.

Usage

Define a mixin in a Sass partial and include it in component rules:

// _mixins.scss
@mixin card-base {
  background: color('white');
  border-radius: radius('md');
  padding: units(3);
  box-shadow: 0 8px 16px 0 rgba(0, 0, 0, 0.1);
}

Then apply it in a component stylesheet:

// _card.scss
.card {
  @include card-base;
}

.card--highlighted {
  @include card-base;
  border-left: units(0.5) solid color('primary');
}

The resulting HTML uses a single semantic class:

<div class="card">
  Component using mixin-generated styles
</div>

Strengths

• Semantic class names that describe purpose, not appearance
• Parameterizable — accept arguments to generate variations
• Bundle multiple properties into a single include

Considerations

• Can duplicate CSS output if the same mixin is included in many selectors
• Requires a Sass build step

Sass Functions

Functions return computed values for use in CSS properties or Sass variables. USWDS provides built-in functions like color(), units(), and radius() that resolve design tokens to their CSS values.

Usage

Use USWDS functions directly in your Sass rules:

// Using USWDS token functions
.card {
  background: color('white');
  padding: units(3);
  border-radius: radius('md');
  color: color('ink');
}

You can also use functions to populate CSS custom properties:

// Setting CSS custom properties with token values
:root {
  --card-bg: #{color('white')};
  --card-padding: #{units(3)};
  --card-shadow: 0 8px 16px 0 rgba(0, 0, 0, 0.1);
}

.card {
  background: var(--card-bg);
  padding: var(--card-padding);
  box-shadow: var(--card-shadow);
}

Strengths

• DRY values — define once, reference everywhere
• Useful for computed or derived values
• Work with CSS custom properties for runtime flexibility

Considerations

• Require a Sass build step
• Values are not visible in markup — must inspect the Sass source

Comparison

Recommendations

• Use utility classes for layout, spacing, and quick styling adjustments directly in markup.
• Use functions to resolve USWDS tokens into values for Sass variables and CSS custom properties.
• Use mixins for semantic component classes that bundle multiple properties (cards, banners, modals).
• All three approaches can be combined — for example, a component might use a mixin for its base styles, functions for its token values, and utility classes for one-off layout adjustments in markup.

Additional Resources

• USWDS Utilities
• USWDS Design Tokens
• Sass Mixins Documentation
• Sass Functions Documentation