Stacks Design System

The @stackoverflow/stacks-email package provides a design system for creating and sending emails to Stack Overflow users. It is built using MJML, an abstraction layer that simplifies email HTML development.

Note: The email design system is currently experimental and subject to change.

Stacks is Stack Overflow's design system, providing resources to build consistent and predictable interfaces that follow Stack Overflow's design language and best practices. It provides:

• Semantic and accessible component markup
• Cross-browser compatible Less / CSS
• An icon library (available via Stacks-Icons)
• Email templates & components

Stacks JavaScript components are implemented as Stimulus controllers. Stimulus allows you to attach functionality to HTML elements using data-... attributes rather than manual event listeners.

Key Concepts

• Controllers: The functional unit of Stimulus. Stacks-provided controllers are always prefixed with s- (e.g., s-magic-widget).
• Activation: You activate a controller by adding the data-controller attribute to an HTML element.

Example of activating a controller:

<div
    class="s-magic-widget s-magic-widget__awesome"
    data-controller="s-magic-widget"
>
</div>

When all child items within a parent container use float properties, the parent container will collapse because floating elements are taken out of the normal DOM order. To prevent this layout bug, apply the .clearfix class to the parent container. This uses a .clearfix() mixin to force the parent to contain its floated children.

<div class="clearfix">
    <div class="float-left">...</div>
    <div class="float-right">...</div>
</div>

When a button switches between selected and unselected states, you must manage both the visual state and accessibility attributes:

1. Visual State: Toggle the .is-selected class.
2. Accessibility: Update the aria-pressed attribute to "true" or "false".
3. Context: Use a title attribute to describe the action if appropriate.

Example implementation logic:

// Toggle logic
let isSelected = toggleButton.getAttribute('aria-pressed') === 'true';
let newState = !isSelected;

toggleButton.classList.toggle('is-selected', newState);
toggleButton.setAttribute('aria-pressed', newState.toString());

<button class="s-btn is-selected" type="button" aria-pressed="true" title="Toggle action">Selected</button>

Emphasis determines the amount of contrast a color has against its default surface. Use emphasis levels to control how much attention an element draws.

Emphasis Levels

1. Bold: Highest contrast. Use this for elements that require significant attention.
   • Example background classes: bg-black-500, bg-orange-400, bg-blue-400.
   • Example text classes: fc-black.
2. Default: Standard contrast level.
   • Example background classes: bg-black-200, bg-orange-200, bg-blue-200.
   • Example text classes: fc-black-500.
3. Subtle: Lowest contrast. Use this for secondary or less important UI elements.
   • Example background classes: bg-black-150, bg-orange-100, bg-blue-100.
   • Example text classes: fc-black-400.

The system categorizes templates along a spectrum from functional to expressive:

• Transactional: Functional emails triggered by specific events. Usually short, single-message communications with a clear call to action.
• Newsletter: Recurring communications that may contain multiple items and various calls to action.
• Promotional: Short, punchy, single-message communications designed to capture attention and drive engagement.

The Highlight variant wraps headline text in a highlighted background that appears as one continuous block across multiple lines. This is best for short, art-directed headlines.

Key behaviors:

• Line Breaks: Controlled by the author using \n in the textContent prop. Each line is wrapped in its own highlighted <span> and joined with <br/>.
• Padding: Vertical padding is applied only to the outer edges (top of the first line and bottom of the last line). Interior lines receive only horizontal padding. This ensures lines join into a single cohesive block rather than appearing as separate 'pills'.
• Alignment: Horizontal padding is constant to ensure left and right edges align.
• Single Line: If no \n is provided, the text is padded on all sides.

To ensure checkboxes are accessible to screen readers, follow these semantic HTML patterns:

• Unique IDs: Every checkbox input must have an id attribute.
• Label Association: Use the for attribute on the <label> element, setting its value to the id of the corresponding input.
• Grouping: For a collection of related checkboxes, wrap them in a <fieldset> and provide a description using a <legend> element.

Stack Overflow uses a specific hierarchy to categorize its offerings. Understanding these distinctions ensures consistent communication across products and materials:

• Mainbrand: The overarching brand (e.g., Stack Overflow).
• Sub-brand: Part of the parent brand, catering to specific segments (e.g., Stack Overflow Business).
• Product: Standalone, externally facing offerings that customers can opt into (e.g., Stack Internal, Stack Ads).
• Feature: Functional aspects or specific actions within a product. Users must have access to the product to use a feature (e.g., Collectives).

To ensure compositions feel balanced and not overwhelming, use neutral tones for backgrounds to offset saturated palette colors.

Exception: Stack Orange may be used as a background color as it is the lead brand color.