Foundation

Foundations are the fundamental building blocks of our design system. They represent the most basic and essential design decisions that ensure visual consistency and maintainability across the entire project.

Think of Foundations as the DNA of the design system - every component, module, and page inherits these core values. By centralizing these tokens, we ensure that any design change can be propagated systematically throughout the entire application.

Key Characteristics:

• Single Source of Truth: All design values are defined once and reused everywhere
• Design-Code Alignment: Direct 1:1 mapping with Figma design tokens
• Scalability: Easy to maintain and update as the design evolves
• Consistency: Ensures visual coherence across all pages and components- Developer Efficiency: Predefined tokens reduce decision-making time

---

Naming conventions

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

.f--{foundation-name}-{variation}

---

Location and Structure

src/scss/framework/foundation/

├── _foundation.scss       # Main foundation index
├── color/                 # Color system
├── font/                  # Typography system
├── spaces/                # Spacing utilities
├── grid/                  # Grid system
├── gap/                   # Gap utilities
├── background/            # Background utilities
└── reset/                 # CSS reset

---

Types of Foundations

Not all foundations serve the same purpose.

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

• Aspect Ratio
• Color
• Background
• Font
• Gap
• Grid
• Reset → Reset is considered a foundation because it defines the base styling of the system. It does not generate any .f-- classes; instead, it normalizes default browser behavior.
• Spaces
• Spacing

Mobile-first approach

All foundation tokens include responsive considerations:

• Typography scales down on mobile
• Spacing reduces on smaller screens
• Grid columns stack at breakpoints

---

Creating foundation classes

Foundation 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 (colors, sizes, spacings, etc.) from a single source of truth

This approach ensures that:

• only the CSS we actually use is generated
• foundations stay predictable and consistent

---

How to use them

Foundations (.f--*) are meant to be used within the component’s SCSS, not directly in the HTML class attribute.

This keeps the HTML clean and ensures that visual logic is encapsulated in the component itself.

Note

This does not mean you can’t use foundation classes in HTML at all — It simply means you should not mix them with the main class of a component.

That means we should avoid this:

❌ Don’t

<div class="c--card-a f--sp-b f--background-a">
  <p class="f--color-c">Text</p>
</div>

✅ Do

<div class="c--card-a">
  <p class="c--card-a__title">Text</p>
</div>

.c--card-a {
  @extend .f--background-a;
  @extend .f--sp-b;
  &__title {
    @extend .f--color-c;
    padding: $measure*2;
    @media all and ($viewport-type:$mobile) {
      padding: $measure*5;
    }
  }
}

---

Foundation order inside components

When using foundations via @extend, order is critical.

Foundations must be applied in a logical, progressive sequence, starting from the base style and layering variations on top. This is not a stylistic choice — it is a requirement for @extend to work correctly.

The rule

• Extend the default foundation first
• Apply modifiers progressively
• Never try to “go back” to a previous foundation

Why order matters

SCSS @extend works by merging selectors at compile time, following the order in which they appear in the cascade. Because of this:

• @extend only works on foundations that have already been applied
• it cannot retroactively include a foundation that comes later
• extending foundations out of order can silently break styles

❌ Don’t

.c--content-a {
  &--second {
    @extend .f--color-b;
  }

  @extend .f--color-a;
}

✅ Do

Imagine a component that supports multiple color variants through modifiers.

.c--content-a {
  @extend .f--color-a;

  &--second {
    @extend .f--color-b;
  }

  &--third {
    @extend .f--color-c;
  }
}

This works because:

• .f--color-a establishes the base color
• .f--color-b and .f--color-c override it progressively
• The compiler can resolve all @extend calls in sequence

This may look correct, but it breaks the cascade. Once .f--color-b is extended, SCSS cannot later apply .f--color-a as a base.