Utilities

Utilities are quick-apply classes designed to apply single CSS properties quickly and consistently. They’re ideal for layout adjustments, visibility rules, alignment, or typographic tweaks without writing custom component styles.

They offer granular control over specific declarations like display, position, text-align, and more. They’re particularly useful for rapid prototyping and making precise adjustments directly in markup.

---

Naming conventions

Utility classes follow a clear and predictable naming pattern. This makes them easy to recognize, easy to extend, and consistent across the entire codebase.

.u--{property}-{value}
.u--{property}-{breakpoint}-{value}

Responsive Support

All utility classes support responsive variations. Use the format .u--{property}-{breakpoint}-{value} to target specific breakpoints.

---

Location

src/scss/framework/utilities/_utilities.scss

---

Types of Utilities

Not all utilities serve the same purpose.

The following sections describe each type of utility and how they are intended to be used within Terra’s framework.

• Align items
• Display
• Flex direction
• Font style
• Font weight
• Height
• Justify content
• Overflow
• Position
• Text align
• Width

---

Creating utility classes

Utility classes are generated using existing mixins and/or loops that iterate over predefined variables or parameters.

• Mixins → encapsulate reusable style logic
• Loops → allow us to generate multiple variations (values, breakpoints, etc.) from a single source of truth

This approach ensures that:

• only the CSS we actually use is generated
• utilities stay predictable and consistent
• responsive variations are automatically created for supported breakpoints

Here’s the step-by-step process for creating new utility classes:

01: Create the Utility File

Create a new SCSS file in src/scss/framework/utilities/ with a descriptive name.

Example: Let’s create cursor utilities. Create file: src/scss/framework/utilities/_cursor.scss

02: Define the Utility Pattern

Use the established pattern with mixins and loops to generate responsive utility classes:

@use "@scss/framework/_var/_vars.scss" as *;

// Define cursor values
$cursor-values: (
  pointer: pointer,
  default: default,
  not-allowed: not-allowed,
  grab: grab,
  grabbing: grabbing,
  move: move,
  text: text,
  wait: wait,
  help: help,
) !default;

// Define breakpoints (if you need responsive cursors)
$cursor-breakpoints: (
  all: $all,
  tablets: $tablets,
  mobile: $mobile,
);

// Create mixin to generate utilities
@mixin cursor-utility($cursor-prop, $breakpoints) {
  @each $breakpoint-name, $breakpoint-value in $breakpoints {
    @if ($breakpoint-value == 0) {
      // Non-responsive utilities
      @each $name, $property in $cursor-prop {
        .u--cursor-#{$name} {
          cursor: $property;
        }
      }
    } @else {
      // Responsive utilities
      @media screen and ($viewport-type: $breakpoint-value) {
        @each $name, $property in $cursor-prop {
          .u--cursor-#{$breakpoint-name}-#{$name} {
            cursor: $property;
          }
        }
      }
    }
  }
}

// Generate utilities
@include cursor-utility($cursor-values, $cursor-breakpoints);

This generates classes like:

.u--cursor-pointer { cursor: pointer; }
.u--cursor-grab { cursor: grab; }
.u--cursor-tablets-pointer { cursor: pointer; } /* at tablets breakpoint */

03: Forward in _utilities.scss

Add your new utility to the main utilities index file:

src/scss/framework/utilities/_utilities.scss
@forward './align-items.scss';
@forward './aspect-ratio.scss';
@forward './display.scss';
// ... existing utilities ...
@forward './cursor.scss'; // ← Add your new utility here

04: Use in HTML

Now you can use your new utilities:

<button class="u--cursor-pointer">Clickable Button</button>
<div class="u--cursor-grab">Draggable Element</div>
<button class="u--cursor-not-allowed" disabled>Disabled Button</button>

---

Best Practices

Do’s ✅

• ✅ Use utilities for common, repeatable styles
• ✅ Follow the established naming convention (u--{property}-{value})
• ✅ Generate responsive variants when appropriate
• ✅ Use $measure for spacing-related utilities
• ✅ Document new utilities in code comments
• ✅ Keep utilities simple and single-purpose

Don’ts ❌

• ❌ Don’t create utilities for complex, component-specific styles
• ❌ Don’t use arbitrary values (always use design tokens)
• ❌ Don’t create too many rare-use utilities (adds to CSS bloat)
• ❌ Don’t override existing utilities unnecessarily
• ❌ Don’t forget to forward new utilities in _utilities.scss