Introduction

A single source of truth for design decisions, reusable patterns, and token-driven components.

This documentation site covers the foundational layers of the WV Design System: brand primitives, semantic aliases, mapped component tokens, and responsive typography and spacing. Every visual decision flows from a structured token architecture that supports light and dark modes across desktop, tablet, and mobile breakpoints.

Token Architecture

The system is built on four collections, each with a strict dependency chain:

1. Brand/Value — Raw primitives (hex colors, spacing scale, font sizes). No semantic meaning.
2. Alias — Semantic intent layer. Maps brand values to roles like Primary, Secondary, Neutral, Information, Success, Error.
3. Mapped (light/dark) — The only layer components consume. Provides Surface, Text, Border, and Icon tokens for each theme mode.
4. Responsive (Desktop/Mobile/Tablet) — Typography scales, jumper spacing, grid settings, and fixed padding per breakpoint.

Getting Started

Browse the sidebar to explore token definitions, component documentation, reusable patterns, and system-level principles. Every component page follows a consistent structure: overview, accessibility, construction specs, variants, usage guidelines, and code examples.

/* Reference a mapped token in CSS */
.card {
  background: var(--surface-default-container);
  border: 1px solid var(--border-default);
  border-radius: var(--radius-m);
  padding: var(--padding-l);
  color: var(--text-body);
}

Color Tokens

Color is organized into brand primitives, semantic aliases, and mapped tokens for light and dark modes.

Primary (Orange)

Secondary (Blue)

Neutral (Gray)

Status Colors

Information (Status Blue)

Success (Status Green)

Error (Status Red)

Mapped Surface Tokens

Global

Surface tokens for page backgrounds, layout containers, action states, and brand colors under Surface/Global/.

Status

Surface tokens for status feedback under Surface/Status/.

Button

Surface tokens for button backgrounds under Surface/Button/.

Secondary

Surface tokens for secondary-branded areas under Surface/Secondary/.

Mapped Text Tokens

Default

Text color tokens under Text/Default/. Action tokens (previously in a separate Action sub-group) are now part of Default.

Status

Text color tokens for status messaging under Text/Status/.

Button

Text color tokens for buttons under Text/Button/.

Mapped Border Tokens

Global

Border color tokens under Border/Global/.

Status

Border color tokens for status feedback under Border/Status/.

Button

Border color tokens for buttons under Border/Button/.

Width

Border width tokens under Border/Width/. Same values for light and dark modes.

Mapped Icon Tokens

Default

Icon color tokens under Icon/Default/. Action tokens (previously in a separate Action sub-group) are now part of Default.

Status

Icon color tokens for status feedback under Icon/Status/.

Button

Icon color tokens for buttons under Icon/Button/.

Brand

Brand icon color tokens under Icon/Brand/.

Shadow Colors (Brand Primitives)

Alpha-channel shadow color primitives derived from the gray scale. These are used by Mapped shadow tokens for light and dark mode elevation effects. Values pending final verification from Figma.

Mapped Shadow Tokens

Semantic shadow color tokens for elevation effects. Each token has a light and dark mode value referencing Brand shadow primitives.

Spacing Tokens

A consistent spacing scale derived from the brand scale. Values follow a roughly doubling progression for the first 100, then increments of 8px.

Base Scale

Scale Reference

Jumper Tokens (Desktop / Tablet / Mobile)

Jumper tokens are responsive spacing values that shrink across breakpoints.

Fixed Padding Tokens

Fixed padding tokens are static spacing values that remain constant across all breakpoints. They are used for internal component spacing such as gaps, padding, and margins.

Grid Margins

Page margins are composed of a Global Margin (the outer gutter) and a Col Margin (the outermost column's margin). On a fixed layout, the total side margin is Global Margin + Col Margin. On a fluid layout, the margin is Global Margin only, allowing content to extend to the column edges.

Usage

.section {
  padding-top: var(--jumper-L-M);
  padding-bottom: var(--jumper-M-S);
  margin-left: var(--grid-global-margin);
  margin-right: var(--grid-global-margin);
  gap: var(--space-300);
}

Corner Radius (Mapped)

Component-specific corner radius tokens in the Mapped collection. These reference Alias Corner Radius values and are identical across light and dark modes. Card radius values pending Figma verification.

Typography Tokens

All type is set in Lato. Icons use Font Awesome 6 Free. Body M (16px) is the baseline reading size. Recommended max-width for body text is 60-75 characters per line for readability.

Overview

To maintain consistency with the grid and spacing increments, the same scaling increments are used for the type scale, with few exceptions, for ease of readability. Medium is the default or baseline size for any context.

Typographic Scale

Heading Scale (Desktop)

Body Scale (Desktop)

Heading + Body Pairings (Mobile)

Each heading size pairs with a corresponding body size for visual hierarchy. Mobile heading sizes are smaller than their desktop counterparts.

Heading + Body Pairings (Desktop)

Desktop heading sizes scale up from mobile. The paired body sizes also shift accordingly.

Text Link Scale

Text links inherit the body size at their corresponding scale but use a heavier weight.

Responsive Comparison

Font Weight Reference

Font weights are stored as numeric values in both the Brand primitives and Responsive collection. Composite typography definitions reference these via Responsive variable paths.

Letter Spacing Reference

Type Scale: Light vs Dark

The type scale uses the same sizes and weights in both modes. Only the text and background colors change between light and dark themes.

Body Copy Comparison

Heading Scale Comparison

Notification Typography

Component-specific typography tokens for Alert and Snackbar notification components. These values are consistent across Desktop, Mobile, and Tablet breakpoints.

Alert

Snackbar

Notification Width

Shadow Blur Sizes (Responsive)

Blur radius values for shadow effects, defined in the Responsive collection. Values are consistent across breakpoints. Pending final verification from Figma.

Alert

Informs users of a process outcome or system event. Compact, inline feedback for form validation results, status changes, and contextual messages.

Overview

The Alert is a compact, inline notification surface used to communicate outcomes or events. For example, if a user submits a form, the alert provides feedback about an error that occurred or confirms the form was completed successfully. Four status variants (Default, Success, Error, Information) control the color of all elements within the alert. The component contains an optional status icon, an optional bold heading, body copy, an optional text link (reusing the Text Link S component), and an optional close button. All optional elements can be included or omitted independently.

Variants

Default

Neutral container with default border. Icon and heading use the headings color, body and close use the body color. Suitable for general feedback or neutral messages.

Success

Green background and border. All text, icons, and the close button use the success color. Use for positive confirmations such as saves, completions, or sends.

Error

Red background and border. All text, icons, and the close button use the error color. Use for failures or issues that need user attention.

Information

Teal background and border. All text, icons, and the close button use the information color. Use for informational notices or system-level messages.

Accessibility Considerations

WCAG 2.1 AA target. Alerts are inline, persistent elements and should not auto-dismiss. They must be perceivable by assistive technology.

Keyboard Interactions

ARIA and Semantics

• Use role="status" for non-critical updates (default, success, information) so screen readers announce content politely.
• Use role="alert" for error alerts to assert immediate attention.
• Include aria-live="polite" (or "assertive" for errors) so content is announced when it appears dynamically.
• The close button must have aria-label="Dismiss" since it contains only an icon.
• If the alert appears after a user action (form submit, etc.), focus management should move the user near the alert.

Construction

The alert is a compact single-row layout. The text link reuses the Text Link S component with status type classes for color matching.

Scale and Spacing

Styles

Color Tokens

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Default with All Options

<div class="alert" role="status" aria-live="polite">
  <div class="alert-icon-text">
    <div class="alert-icon">
      <i class="fa-solid fa-circle-info"></i>
    </div>
    <div class="alert-text">
      <div class="alert-heading">Changes saved</div>
      <div class="alert-body">Your profile has been updated.</div>
      <a class="text-link text-link-s" href="#">
        <span class="link-label">Link</span>
        <i class="link-icon fa-solid fa-chevron-right"></i>
      </a>
    </div>
  </div>
  <button class="alert-close" aria-label="Dismiss">
    <i class="fa-solid fa-xmark"></i>
  </button>
</div>

Error Alert

<div class="alert alert-error" role="alert" aria-live="assertive">
  <div class="alert-icon-text">
    <div class="alert-icon">
      <i class="fa-solid fa-circle-exclamation"></i>
    </div>
    <div class="alert-text">
      <div class="alert-heading">Submission failed</div>
      <div class="alert-body">Please correct the errors and try again.</div>
      <a class="text-link text-link-s type-error" href="#">
        <span class="link-label">Link</span>
        <i class="link-icon fa-solid fa-chevron-right"></i>
      </a>
    </div>
  </div>
  <button class="alert-close" aria-label="Dismiss">
    <i class="fa-solid fa-xmark"></i>
  </button>
</div>

Minimal (No Icon, No Link, No Close)

<div class="alert alert-success" role="status" aria-live="polite">
  <div class="alert-icon-text">
    <div class="alert-text">
      <div class="alert-body">Registration complete.</div>
    </div>
  </div>
</div>

Breadcrumbs

A horizontal navigation pattern that shows the user's current location within a site hierarchy. Each crumb is a clickable link except the last item, which represents the current page.

Overview

Breadcrumbs help users understand where they are in a multi-level navigation structure and provide quick access to parent pages. The component uses Small Link (S) typography (Lato Bold, 14px/18px) with --text-body as the default color. On hover, all elements within a crumb (text, icons, separator) change to --text-action-hover. A chevron-right icon (fa-chevron-right) separates each crumb. The first crumb includes a home icon (fa-house). The last crumb (current page) displays a persistent underline and has no trailing separator.

Variants

Assembled Breadcrumb

Full breadcrumb trail with home icon, intermediate links, and current page.

First Item

Includes a home icon (left), label text, and a chevron-right separator (right).

Middle Item

Label text with a chevron-right separator. No home icon.

Last Item (Current Page)

Label text only, with a persistent underline. No trailing chevron separator.

Accessibility Considerations

WCAG 2.1 AA target. Breadcrumbs expose hierarchy and current location; focus order follows the visual trail left to right.

Keyboard Interactions

ARIA and Semantics

• Wrap the trail in <nav aria-label="Breadcrumb"> (or another concise label).
• Add aria-current="page" to the last (current) item.
• Home icon and chevron separators use aria-hidden="true".
• Disabled crumbs use <span> instead of <a> so they are not in the tab order.
• Focus indicator: 2px solid --border-action, 6px outline offset from the crumb, 10px radius (--radius-focus-ring), matching the Small Link focus treatment in Figma.

Construction

Typography

Color Tokens

Focus Ring

Spacing

Application and Context

For Developers

For Designers

Usage Examples

Standard Breadcrumb

<nav class="breadcrumb" aria-label="Breadcrumb">
  <a class="breadcrumb-item" href="/home">
    <i class="breadcrumb-icon fa-solid fa-house" aria-hidden="true"></i>
    <span>Home</span>
    <i class="breadcrumb-icon fa-solid fa-chevron-right" aria-hidden="true"></i>
  </a>
  <a class="breadcrumb-item" href="/components">
    <span>Components</span>
    <i class="breadcrumb-icon fa-solid fa-chevron-right" aria-hidden="true"></i>
  </a>
  <a class="breadcrumb-item current" href="/components/button" aria-current="page">
    <span class="link-label">Button</span>
  </a>
</nav>

Breadcrumb with Disabled Item

<nav class="breadcrumb" aria-label="Breadcrumb">
  <a class="breadcrumb-item" href="/home">
    <i class="breadcrumb-icon fa-solid fa-house" aria-hidden="true"></i>
    <span>Home</span>
    <i class="breadcrumb-icon fa-solid fa-chevron-right" aria-hidden="true"></i>
  </a>
  <span class="breadcrumb-item is-disabled">
    <span>Archived</span>
    <i class="breadcrumb-icon fa-solid fa-chevron-right" aria-hidden="true"></i>
  </span>
  <a class="breadcrumb-item current" href="/archived/report" aria-current="page">
    <span class="link-label">Report</span>
  </a>
</nav>

Button

Triggers an action or event. The primary mechanism for user-initiated operations across dialogs, forms, cards, and toolbars.

Overview

Buttons communicate actions users can take. They use the primary (orange) action color to establish visual hierarchy. Two variants exist: Primary (filled) for the most important action, and Outline (bordered) for secondary actions. Four sizes (S, M, L, XL) allow density control across layouts. Each button supports optional leading and trailing icons via Font Awesome 6.

Variants

Primary (Filled)

Solid background with a lighter border. White text and icons on the default state. Used for the highest-priority action in a view.

Outline (Bordered)

Transparent background with a colored border. Text and icons use the action color. Used for secondary actions or when paired alongside a Primary button.

Sizes

Four density levels control vertical padding and font size.

Accessibility Considerations

WCAG 2.1 AA target. Uses the native <button> element with implicit role="button".

Keyboard Interactions

Focus Management

• Focus ring: 2px solid border, offset 6px outward from the button edge, matching the button's pill radius (48px).
• Primary focus ring uses Border/Button/Primary/border (#f78958).
• Outline focus ring uses Border/Button/Primary/outline (#e96620).
• Focus state does not change background or text color from default.

Disabled State

• Uses aria-disabled="true" to remain in tab order for discoverability.
• Text and icon color: Text/Action/action-disabled (#979797). Reduced contrast but still legible against both filled (#f5f5f5) and page (#fafafa) backgrounds.

Construction

Scale and Spacing

Styles

Color Tokens: Primary Variant

Color Tokens: Outline Variant

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Basic

<button class="btn btn-primary btn-m" type="button">Submit</button>
<button class="btn btn-outline btn-m" type="button">Cancel</button>

With Icons

<button class="btn btn-primary btn-m" type="button">
  <span class="btn-icon">&#xf05a;</span>
  Button
  <span class="btn-icon">&#xf05a;</span>
</button>

All Sizes

<button class="btn btn-primary btn-s" type="button">Small</button>
<button class="btn btn-primary btn-m" type="button">Medium</button>
<button class="btn btn-primary btn-l" type="button">Large</button>
<button class="btn btn-primary btn-xl" type="button">XLarge</button>

Disabled

<button class="btn btn-primary btn-m" disabled aria-disabled="true">
  <span class="btn-icon">&#xf05a;</span>
  Unavailable
</button>

<button class="btn btn-outline btn-m" disabled aria-disabled="true">
  <span class="btn-icon">&#xf05a;</span>
  Unavailable
</button>

Button Group

A segmented control that groups related actions into a single horizontal strip, allowing users to choose between options or toggle views.

Overview

Button groups combine two or more related actions into a connected row of segments. Each segment behaves like an individual button but shares a container border and divider treatment that communicates they belong together. Two types exist: Labeled (icon + text) and Icon-only (compact, icon without text). Items support four states: Default, Hover, Selected, and Disabled. The component uses role="group" with an aria-label describing the group purpose.

Variants

Labeled (Icon + Text)

Each segment contains a leading icon and a text label. The full-width variant used when labels are needed to clarify the action.

Icon-only

Compact variant where each segment contains only an icon. Use when space is tight and the icons are universally understood. Every icon-only item must have an aria-label.

Accessibility Considerations

WCAG 2.1 AA target. The group container communicates that the buttons are related.

Keyboard Interactions

ARIA Requirements

• The container must have role="group" and an aria-label describing the group purpose.
• The selected item should have aria-pressed="true" (toggle behavior) or be managed via aria-current for navigation.
• Icon-only items must include aria-label on each button.
• Disabled items use aria-disabled="true" to remain discoverable.

Focus Management

• Focus indicator: 2px solid outline in --surface-action, inset 2px. Contained within the group border.
• Focus does not change background or text color from the current state.

Construction

Scale and Spacing

Styles

Color Tokens

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Labeled Group

<div class="btn-group" role="group" aria-label="View options">
  <button class="btn-group-item" type="button">
    <i class="btn-group-icon fa-solid fa-list"></i> List
  </button>
  <button class="btn-group-item selected" type="button"
          aria-pressed="true">
    <i class="btn-group-icon fa-solid fa-grip"></i> Grid
  </button>
  <button class="btn-group-item" type="button">
    <i class="btn-group-icon fa-solid fa-table"></i> Table
  </button>
</div>

Icon-only Group

<div class="btn-group" role="group" aria-label="Actions">
  <button class="btn-group-item btn-group-icon-only"
          type="button" aria-label="Mail">
    <i class="btn-group-icon fa-solid fa-envelope"></i>
  </button>
  <button class="btn-group-item btn-group-icon-only"
          type="button" aria-label="Info">
    <i class="btn-group-icon fa-solid fa-circle-info"></i>
  </button>
  <button class="btn-group-item btn-group-icon-only"
          type="button" aria-label="Favorite">
    <i class="btn-group-icon fa-solid fa-heart"></i>
  </button>
</div>

With Selected and Disabled Items

<div class="btn-group" role="group" aria-label="Alignment">
  <button class="btn-group-item selected" type="button"
          aria-pressed="true">
    <i class="btn-group-icon fa-solid fa-align-left"></i> Left
  </button>
  <button class="btn-group-item" type="button">
    <i class="btn-group-icon fa-solid fa-align-center"></i> Center
  </button>
  <button class="btn-group-item" type="button"
          disabled aria-disabled="true">
    <i class="btn-group-icon fa-solid fa-align-right"></i> Right
  </button>
</div>

Carousel

The Carousel is used to scroll through a series of images, cards, or other content blocks. Left and right navigation buttons advance the content, and a progress bar reflects the current scroll position.

Overview

The Carousel provides horizontal navigation through a set of content items that exceed the visible viewport. It consists of three atomic parts: a left button (chevron-left), a progress bar, and a right button (chevron-right). The buttons advance the content one item at a time, and the progress bar fills proportionally to indicate how far the user has scrolled. The carousel is designed to be scalable: any number of content items can be placed in the track, and the controls adapt automatically. When the first item is visible, the left button is disabled. When the last item is visible, the right button is disabled.

Variants

Navigation Button - Left

Pill-shaped button with a chevron-left icon. Navigates the carousel content one step backward.

Navigation Button - Right

Pill-shaped button with a chevron-right icon. Navigates the carousel content one step forward.

Progress Bar

An 8px-tall track with a proportional fill that reflects the current scroll position. The fill width and position update as the user navigates.

Assembled Controls

The three atomic parts combined into a single control bar: left button, progress bar, and right button.

Working Demo

A functional carousel with content cards. Click the left/right buttons to scroll. The progress bar updates to reflect the current position. The left button is disabled at the start; the right button is disabled at the end.

Accessibility Considerations

WCAG 2.1 AA target. The carousel must be fully navigable by keyboard and clearly indicate its boundaries and current position to assistive technology.

Keyboard Interactions

ARIA and Semantics

• The carousel container should use role="region" with an aria-label describing the content (e.g., "Featured stories").
• Navigation buttons require aria-label="Previous" and aria-label="Next".
• Disabled buttons must have the disabled attribute and aria-disabled="true".
• The progress bar is decorative and should use aria-hidden="true".
• Content items within the track should have role="group" with aria-roledescription="slide" and aria-label="N of M".

Construction

The Carousel is composed of three atomic parts (left button, progress bar, right button) assembled into a control bar, placed below or above a viewport that clips the scrollable content track.

Scale and Spacing

Styles

Color Tokens

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Basic Carousel

<div class="carousel" data-carousel role="region" aria-label="Featured stories">
  <div class="carousel-viewport">
    <div class="carousel-track">
      <div role="group" aria-roledescription="slide" aria-label="1 of 4">...</div>
      <div role="group" aria-roledescription="slide" aria-label="2 of 4">...</div>
      <div role="group" aria-roledescription="slide" aria-label="3 of 4">...</div>
      <div role="group" aria-roledescription="slide" aria-label="4 of 4">...</div>
    </div>
  </div>
  <div class="carousel-controls">
    <button class="carousel-btn" type="button" aria-label="Previous" data-carousel-prev>
      <i class="fa-solid fa-chevron-left"></i>
    </button>
    <div class="carousel-bar" aria-hidden="true">
      <div class="carousel-bar-fill" data-carousel-fill></div>
    </div>
    <button class="carousel-btn" type="button" aria-label="Next" data-carousel-next>
      <i class="fa-solid fa-chevron-right"></i>
    </button>
  </div>
</div>

Controls Only (No Content)

<div class="carousel-controls">
  <button class="carousel-btn" type="button" aria-label="Previous">
    <i class="fa-solid fa-chevron-left"></i>
  </button>
  <div class="carousel-bar" aria-hidden="true">
    <div class="carousel-bar-fill" style="left:0%; width:25%;"></div>
  </div>
  <button class="carousel-btn" type="button" aria-label="Next">
    <i class="fa-solid fa-chevron-right"></i>
  </button>
</div>

Checkbox

A form control that allows users to select one or more options from a set. Pairs a 24x24 indicator box with an optional text label.

Overview

The checkbox is a binary selection control. When checked, it displays a Font Awesome check icon inside an action-colored fill. When unchecked, it renders as a bordered empty square. The component supports five states (default, hover, focus, disabled, error) across both selected and unselected types. An optional label sits to the right with an 8px gap.

Variants

Unselected

Empty checkbox with action-colored border and page-colored background. Shows the available selection target.

Selected

Filled checkbox with a white check icon. The action-colored background confirms the selection.

With Label

Checkbox paired with a Body M label (Lato Regular, 16px/26px) at an 8px gap.

Accessibility Considerations

WCAG 2.1 AA target. Checkboxes must be operable by keyboard and clearly communicate their checked/unchecked state to assistive technology.

Keyboard Interactions

ARIA and Semantics

• Use native <input type="checkbox"> inside a <label> for automatic association. This provides the checked/unchecked state to screen readers without extra ARIA.
• When the label wraps the input, no for/id pairing is needed.
• For checkbox groups, wrap in a <fieldset> with a <legend> describing the group.
• Error state should be paired with aria-describedby pointing to an error message element and aria-invalid="true" on the input.
• Disabled checkboxes use the native disabled attribute, which removes them from tab order.
• Focus ring: 2px solid --border-action, 3px offset, 4px border-radius.

Construction

Scale and Spacing

Styles

Color Tokens

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Single Checkbox with Label

<label class="form-checkbox">
  <input type="checkbox">
  I agree to the Terms of Service
</label>

Checkbox Group

<fieldset>
  <legend>Select your interests</legend>
  <label class="form-checkbox">
    <input type="checkbox" name="interests" value="design">
    Design
  </label>
  <label class="form-checkbox">
    <input type="checkbox" name="interests" value="dev">
    Development
  </label>
  <label class="form-checkbox">
    <input type="checkbox" name="interests" value="research">
    Research
  </label>
</fieldset>

Error State with Message

<label class="form-checkbox">
  <input type="checkbox" class="has-error"
         aria-invalid="true"
         aria-describedby="cb-err">
  Accept privacy policy
</label>
<span id="cb-err" class="input-hint hint-error">
  You must accept to continue.
</span>

Disabled Checkbox

<label class="form-checkbox">
  <input type="checkbox" disabled>
  This option is unavailable
</label>

Icon Button

A compact button containing only an icon, used for actions where the icon alone communicates intent.

Overview

Icon buttons are a density-optimized variant of the standard button. They remove the text label and use uniform padding on all sides so the button renders as a circle. Two variants exist: Primary (filled) and Outline (bordered). Three sizes (S, M, L) match the standard button size scale. Icons are rendered via Font Awesome 6 Free (Solid weight). Because there is no visible label, every Icon Button must have an aria-label.

Variants

Primary (Filled)

Solid orange background with a lighter border. White icon. Same color token set as the standard Primary button.

Outline (Bordered)

Page-color background with an orange border. Icon uses the action color. Same color token set as the standard Outline button.

Accessibility Considerations

WCAG 2.1 AA target. Because there is no visible text label, an accessible name is required.

Keyboard Interactions

ARIA Requirements

• Every icon button must include aria-label describing the action (e.g., aria-label="More information").
• If the icon button toggles state, use aria-pressed to communicate the current value.
• Focus ring: same 2px solid, 6px outward offset, pill radius as the standard button.

Construction

Scale and Spacing

Styles

Color Tokens

Identical to the standard Button component. See the Button color token tables for the full Primary and Outline state mappings.

Application and Context

For Developers

For Designers

Usage Examples

Basic

<button class="btn btn-primary btn-icon-only btn-m"
        type="button"
        aria-label="More information">
  <i class="btn-icon fa-solid fa-circle-info"></i>
</button>

<button class="btn btn-outline btn-icon-only btn-m"
        type="button"
        aria-label="More information">
  <i class="btn-icon fa-solid fa-circle-info"></i>
</button>

All Sizes

<button class="btn btn-primary btn-icon-only btn-s" aria-label="Info">
  <i class="btn-icon fa-solid fa-circle-info"></i>
</button>
<button class="btn btn-primary btn-icon-only btn-m" aria-label="Info">
  <i class="btn-icon fa-solid fa-circle-info"></i>
</button>
<button class="btn btn-primary btn-icon-only btn-l" aria-label="Info">
  <i class="btn-icon fa-solid fa-circle-info"></i>
</button>

Disabled

<button class="btn btn-primary btn-icon-only btn-m"
        disabled aria-disabled="true" aria-label="Info">
  <i class="btn-icon fa-solid fa-circle-info"></i>
</button>

Input

A single-line text field that combines a label, input field with optional icons, and hint text into a complete form control.

Overview

The Input component is a composed form control made up of three sub-elements: a Label (with optional info icon and required indicator), a Field (with optional leading and trailing icons), and optional Hint Text. It supports four interaction states (default, hover, focus, disabled) and three validation states (error, success, information). The Input is also used within the Forms pattern. All field text uses Lato Regular at Body M (16px/26px). Hint text uses Body S (14px/18px). Icons use Font Awesome 6 Solid at 16px.

Variants

Label

The label sits above the field. It pairs text with an optional trailing info icon. The required variant positions a red asterisk to the left of the label text (per WCAG best practice).

Field States

The field supports four interaction states combined with two content states: Pre-filled (placeholder text visible, field is empty) and Not Pre-filled (user has entered text). In the pre-filled state, icons and text use --text-placeholder to signal the field awaits input.

Pre-filled (Placeholder)

When the field is empty, placeholder text and icons display in --text-placeholder.

Not Pre-filled (Typed Text)

Once the user has entered text, icons and text use --text-body or the current interaction-state color.

Validation States

Validation feedback colors the field border, trailing icon, and hint text to indicate status. The trailing icon changes to fa-circle-check for success and fa-circle-xmark for error and information.

Assembled Input

The full Input component with Label, Field, and Hint Text.

Accessibility Considerations

WCAG 2.1 AA target. Every input must be associated with a visible label for assistive technology.

Keyboard Interactions

ARIA and Semantics

• Use <label for="id"> or wrap the input in a <label> to associate the label with the field.
• Add aria-required="true" to required fields. The visual asterisk is decorative via CSS ::before.
• Connect hint/validation text via aria-describedby pointing to the hint element's id.
• Set aria-invalid="true" on the input when in an error state.
• Leading and trailing icons are decorative and must include aria-hidden="true".
• Use the native disabled attribute on <input> to remove disabled fields from tab order automatically.

Construction

The Input is composed of three sub-elements stacked vertically: Label, Field, and Hint Text. All three sit inside a flex-column container (.input-group) with 8px gap.

Scale and Spacing

Styles

Color Tokens

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Basic Input with Label and Hint

<div class="input-group">
  <label class="input-label" for="fname">
    First name
    <i class="label-icon fa-solid fa-circle-question" aria-hidden="true"></i>
  </label>
  <div class="form-field">
    <i class="field-icon fa-solid fa-user" aria-hidden="true"></i>
    <input type="text" id="fname" placeholder="First name">
    <i class="field-icon fa-solid fa-circle-xmark" aria-hidden="true"></i>
  </div>
  <span class="input-hint">Hint text</span>
</div>

Required Input

<div class="input-group">
  <label class="input-label label-required" for="email">
    Email
    <i class="label-icon fa-solid fa-circle-question" aria-hidden="true"></i>
  </label>
  <div class="form-field">
    <i class="field-icon fa-solid fa-envelope" aria-hidden="true"></i>
    <input type="email" id="email" placeholder="Email address"
           aria-required="true">
    <i class="field-icon fa-solid fa-circle-xmark" aria-hidden="true"></i>
  </div>
</div>

Input with Error Validation

<div class="input-group">
  <label class="input-label" for="email-err">Email</label>
  <div class="form-field field-error">
    <i class="field-icon fa-solid fa-envelope" aria-hidden="true"></i>
    <input type="email" id="email-err" placeholder="Email"
           aria-invalid="true" aria-describedby="email-err-hint">
    <i class="field-icon field-status-icon
              fa-solid fa-circle-xmark" aria-hidden="true"></i>
  </div>
  <span class="input-hint hint-error"
        id="email-err-hint">Please enter a valid email.</span>
</div>

Input with Success Validation

<div class="input-group">
  <label class="input-label" for="email-ok">Email</label>
  <div class="form-field field-success">
    <i class="field-icon fa-solid fa-envelope" aria-hidden="true"></i>
    <input type="email" id="email-ok" placeholder="Email"
           aria-describedby="email-ok-hint">
    <i class="field-icon field-status-icon
              fa-solid fa-circle-check" aria-hidden="true"></i>
  </div>
  <span class="input-hint hint-success"
        id="email-ok-hint">Email verified successfully.</span>
</div>

Selector Accordion

Overview

A collapsible dropdown list that organises selectable options under a category header. Clicking the header expands a panel of options; clicking an option selects it.

The Selector Accordion is built from two sub-components: a Category header (with label and chevron icon) and Option items. The category header toggles between collapsed and expanded states. When expanded, options appear in a connected list below the header. The last option receives bottom border-radius to close the visual container. Options can be unselected, selected, or disabled. The category header and all options share a consistent set of interaction states (default, hover, pressed, disabled). Category text uses Body M (16px/26px). Option text uses Body S (14px/18px). The chevron icon uses Font Awesome 6 Solid.

Variants

Category Header (Collapsed)

The category header in its collapsed state. A chevron-down icon indicates the selector accordion can be expanded.

Category Header (Expanded)

When expanded, the category header loses its bottom border-radius, connecting visually to the options below. The chevron rotates 180 degrees.

Option States (Drop-down options that are unselected)

Individual option rows within an expanded selector accordion. Options use Body S typography. These show the unselected variant.

Option States (Drop-down options that are selected)

Options in the selected state, indicating the currently chosen value.

Last Option Focus

The last option in a selector accordion receives bottom border-radius on its focus ring using --radius-focus-ring (10px) to match the container shape.

Assembled Selector Accordion

The full Selector Accordion component with a label, an info icon, and a dropdown. The category header toggles expanded/collapsed on click.

Working Demo

Click the category header to expand or collapse. Click an option to select it.

Accessibility Considerations

WCAG 2.1 AA target. The Selector Accordion should behave as a disclosure widget: the category header is a <button> that toggles visibility of the options panel.

Keyboard Interactions

ARIA and Semantics

• The category header must be a <button> with aria-expanded="true|false".
• Use aria-controls on the header pointing to the options container's id.
• Options should use role="option" or be native <button> elements.
• The selected option should include aria-selected="true" or aria-current="true".
• Disabled options must include the disabled attribute and aria-disabled="true".
• The chevron icon is decorative: add aria-hidden="true".

Construction

The Selector Accordion is composed of a label row, a category header, and an options panel. The label sits above the header in a flex-column container with an 8px gap. Wrap the category button and the options panel in .sel-accordion-stack so the pair gets a definite width inside flex layouts (for example documentation state rows or the Filter pattern). The options panel stacks vertically below the header with no gap, creating a seamless bordered list.

Scale and Spacing

Styles

Color Tokens for Category Header

Color Tokens for Drop-Down Options

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Basic Selector Accordion (collapsed)

<div class="sel-accordion-group">
  <div class="sel-accordion-label">Category <i class="label-icon fa-solid fa-circle-question"></i></div>
  <div>
    <button class="sel-accordion-category" type="button" aria-expanded="false" aria-controls="sel-accordion-options">
      <span>Select option</span>
      <i class="sel-accordion-icon fa-solid fa-chevron-down" aria-hidden="true"></i>
    </button>
    <div class="sel-accordion-dropdown" id="sel-accordion-options" hidden>
      <button class="sel-accordion-option" type="button">Option A</button>
      <button class="sel-accordion-option" type="button">Option B</button>
      <button class="sel-accordion-option" type="button">Option C</button>
    </div>
  </div>
</div>

Expanded with selected option

<div class="sel-accordion-group">
  <div class="sel-accordion-label">Category</div>
  <div>
    <button class="sel-accordion-category is-expanded" type="button" aria-expanded="true" aria-controls="sel-accordion-opts">
      <span>Category</span>
      <i class="sel-accordion-icon fa-solid fa-chevron-down" aria-hidden="true"></i>
    </button>
    <div class="sel-accordion-dropdown" id="sel-accordion-opts">
      <button class="sel-accordion-option" type="button">Option A</button>
      <button class="sel-accordion-option is-selected" type="button" aria-selected="true">Option B</button>
      <button class="sel-accordion-option" type="button">Option C</button>
    </div>
  </div>
</div>

Menu

Overview

A vertical list of navigational items used in sidebars or flyout panels. Each item contains an optional left icon, a text label, and an optional right arrow icon.

The Menu is a navigation component for mobile sidebars and flyout panels. Each menu item is a full-width row with consistent padding, a 2px bottom border, and support for left and right icons. Items can be unselected, selected (indicating the current page/section), or disabled. When assembled, items stack inside a bordered container with rounded corners. The first and last items receive top and bottom border-radius respectively.

Variants

Menu Item (Unselected)

Individual menu items in the unselected state across all interaction states.

Menu Item (Selected)

Menu items in the selected state, indicating the currently active page or section.

Assembled Menu

Menu items stacked in a bordered container. One item is selected. The container has rounded corners with 1px side/top borders. Each item's 2px bottom border separates rows; the last item has no bottom border.

Working Demo

Click a menu item to select it. The previously selected item returns to its default state.

Accessibility Considerations

WCAG 2.1 AA target. The Menu should use <nav> with an aria-label for navigation context. Items should be focusable <button> or <a> elements.

Keyboard Interactions

ARIA and Semantics

• Wrap items in a <nav> element with a descriptive aria-label.
• The selected item should include aria-current="page" to indicate the active page.
• Disabled items must include the disabled attribute and aria-disabled="true".
• Left and right icons are decorative: add aria-hidden="true".

Construction

The Menu is a <nav> container wrapping a vertical stack of menu item <button> or <a> elements. The container provides the outer border and border-radius. Each item provides its own 2px bottom border as a separator, except the last item.

Scale and Spacing

Styles

Color Tokens

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Basic Menu

<nav class="menu-nav" aria-label="Main navigation">
  <button class="menu-item" type="button">
    <i class="menu-item-icon fa-solid fa-house" aria-hidden="true"></i>
    <span class="menu-item-label">Dashboard</span>
    <i class="menu-item-icon fa-solid fa-arrow-right" aria-hidden="true"></i>
  </button>
  <button class="menu-item is-selected" type="button" aria-current="page">
    <i class="menu-item-icon fa-solid fa-user" aria-hidden="true"></i>
    <span class="menu-item-label">Profile</span>
    <i class="menu-item-icon fa-solid fa-arrow-right" aria-hidden="true"></i>
  </button>
  <button class="menu-item" type="button">
    <i class="menu-item-icon fa-solid fa-gear" aria-hidden="true"></i>
    <span class="menu-item-label">Settings</span>
    <i class="menu-item-icon fa-solid fa-arrow-right" aria-hidden="true"></i>
  </button>
</nav>

Progress Bar

A horizontal indicator that communicates the completion status of a task or process.

Overview

The progress bar shows how far along a process is by filling a horizontal track from left to right. It comes in two sizes: Desktop (8px track) and Mobile (4px track). An optional label row above the bar displays a text descriptor and a percentage value. The bar uses the action color for the fill against a light tinted track. Width of the fill is controlled via inline style or JavaScript.

Variants

Desktop (Default)

8px track height with a 20px/24px bold label. Use on desktop viewports.

Mobile (Small)

4px track height with a 16px/20px bold label. Use on mobile viewports or in compact layouts.

Accessibility Considerations

WCAG 2.1 AA target. Progress bars must communicate their current value to assistive technology.

Keyboard Interactions

ARIA and Semantics

• Use role="progressbar" on the track element.
• Set aria-valuenow to the current percentage (e.g. 80).
• Set aria-valuemin="0" and aria-valuemax="100".
• Include aria-label describing the process (e.g. "Upload progress") when no visible label is present.
• When a visible label exists, use aria-labelledby pointing to the label element's id.
• For indeterminate progress (unknown completion), omit aria-valuenow and add an animation to the fill.

Construction

Scale and Spacing

Styles

Color Tokens

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Desktop with Label

<div class="progress-bar">
  <div class="progress-bar-label">
    <span class="progress-bar-label-text">Completion:</span>
    <span class="progress-bar-label-value">80%</span>
  </div>
  <div class="progress-bar-track"
       role="progressbar"
       aria-valuenow="80"
       aria-valuemin="0"
       aria-valuemax="100"
       aria-label="Completion">
    <div class="progress-bar-fill" style="width:80%"></div>
  </div>
</div>

Mobile without Label

<div class="progress-bar progress-bar-sm">
  <div class="progress-bar-track"
       role="progressbar"
       aria-valuenow="60"
       aria-valuemin="0"
       aria-valuemax="100"
       aria-label="Upload progress">
    <div class="progress-bar-fill" style="width:60%"></div>
  </div>
</div>

Desktop without Label

<div class="progress-bar">
  <div class="progress-bar-track"
       role="progressbar"
       aria-valuenow="45"
       aria-valuemin="0"
       aria-valuemax="100"
       aria-label="Processing">
    <div class="progress-bar-fill" style="width:45%"></div>
  </div>
</div>

Radio Button

A form control that allows users to select exactly one option from a mutually exclusive set. Pairs a 24px circular indicator with an optional text label.

Overview

The radio button is a single-select control used inside groups of two or more options. When selected, it displays a small white dot centered inside an action-colored fill. When unselected, it renders as a bordered empty circle. The component supports five states (default, hover, focus, disabled, error) across both selected and unselected types. An optional label sits to the right with an 8px gap. The container has 4px vertical padding to provide comfortable touch/click targets.

Variants

Unselected

Empty circle with action-colored border. Shows the available selection target.

Selected

Filled circle with a centered white dot. The action-colored background confirms the selection.

With Label

Radio button paired with a Body M label (Lato Regular, 16px/26px) at an 8px gap.

Accessibility Considerations

WCAG 2.1 AA target. Radio buttons must be operable by keyboard and clearly communicate their selected/unselected state to assistive technology.

Keyboard Interactions

ARIA and Semantics

• Use native <input type="radio"> inside a <label> for automatic association. All radios in a group must share the same name attribute.
• Wrap the group in a <fieldset> with a <legend> describing the question or category.
• For custom implementations, use role="radiogroup" on the container and role="radio" with aria-checked on each option.
• Error state should be paired with aria-describedby pointing to an error message element and aria-invalid="true" on the input.
• Disabled radio buttons use the native disabled attribute, which removes them from tab order.
• Focus ring: 2px solid --border-action, 2px offset, fully rounded.

Construction

Scale and Spacing

Styles

Color Tokens

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Radio Group with Fieldset

<fieldset>
  <legend>Preferred contact method</legend>
  <label class="form-radio">
    <input type="radio" name="contact" value="email">
    Email
  </label>
  <label class="form-radio">
    <input type="radio" name="contact" value="phone">
    Phone
  </label>
  <label class="form-radio">
    <input type="radio" name="contact" value="text">
    Text message
  </label>
</fieldset>

Pre-selected Option

<fieldset>
  <legend>Frequency</legend>
  <label class="form-radio">
    <input type="radio" name="freq" value="daily" checked>
    Daily
  </label>
  <label class="form-radio">
    <input type="radio" name="freq" value="weekly">
    Weekly
  </label>
</fieldset>

Error State with Message

<fieldset aria-describedby="rb-err">
  <legend>Select a plan</legend>
  <label class="form-radio">
    <input type="radio" name="plan" value="basic"
           class="has-error" aria-invalid="true">
    Basic
  </label>
  <label class="form-radio">
    <input type="radio" name="plan" value="pro"
           class="has-error" aria-invalid="true">
    Pro
  </label>
</fieldset>
<span id="rb-err" class="input-hint hint-error">
  Please select a plan to continue.
</span>

Disabled Radio

<label class="form-radio">
  <input type="radio" name="tier" value="enterprise" disabled>
  Enterprise (coming soon)
</label>

Snackbar

The Snackbar as a brief, modal notification to the user for things such as: A new fundraising campaign just launched, a new press release has been posted to the website, fundraising and sign-ups have opened for enrollment for Team World Vision, the user started setting up their account but hasn’t finished, etc.

Overview

The snackbar is a lightweight feedback surface at a minimum of 336px width. It contains an optional status icon, a bold heading, body copy, an optional "Learn More" text link, a close button, and an optional progress bar (using the Progress Bar SM component) along the bottom edge. Four status variants (Default, Success, Error, Information) control the icon and heading color while body text stays neutral. All optional elements (icon, link, close, progress bar) can be included or omitted independently.

Variants

Default

Action/brand color for icon and heading. Use for general confirmations or neutral status updates.

Success

Green icon and heading for positive confirmations such as saves, completions, or sends.

Error

Red icon and heading for failures or destructive outcomes that need user attention.

Information

Teal icon and heading for informational notices or system-level messages.

Accessibility Considerations

WCAG 2.1 AA target. Snackbars must not block interaction and should be perceivable by assistive technology without stealing focus.

Keyboard Interactions

ARIA and Semantics

• Use role="status" for non-critical updates (default, success, information) so screen readers announce content politely.
• Use role="alert" for error snackbars to assert immediate attention.
• Include aria-live="polite" (or "assertive" for errors) so content is announced when it appears.
• The close button must have aria-label="Dismiss" since it contains no visible text.
• If the snackbar auto-dismisses, the timeout should be at least 5 seconds. Provide a way to pause or extend.
• The snackbar must not trap focus or prevent interaction with the rest of the page.

Construction

The snackbar composes several sub-elements. The embedded progress bar reuses the Progress Bar SM component. The text link reuses the Body Link M pattern from the Text Link component.

Scale and Spacing

Styles

Color Tokens

Application and Context

For Developers

For Designers

Spacing Guidance

Usage Examples

Default with All Options

<div class="snackbar" role="status" aria-live="polite">
  <div class="snackbar-content">
    <div class="snackbar-icon-text">
      <div class="snackbar-icon">
        <i class="fa-solid fa-circle-info"></i>
      </div>
      <div class="snackbar-text">
        <div class="snackbar-heading">Changes saved</div>
        <div class="snackbar-body">Your profile has been updated.</div>
        <a class="text-link text-link-m" href="#">
          <span class="link-label">Learn More</span>
          <i class="link-icon fa-solid fa-chevron-right"></i>
        </a>
      </div>
    </div>
    <button class="snackbar-close" aria-label="Dismiss">
      <i class="fa-solid fa-xmark"></i>
    </button>
  </div>
  <div class="progress-bar progress-bar-sm">
    <div class="progress-bar-track">
      <div class="progress-bar-fill" style="width:60%"></div>
    </div>
  </div>
</div>

Error without Progress Bar

<div class="snackbar snackbar-error" role="alert" aria-live="assertive">
  <div class="snackbar-content">
    <div class="snackbar-icon-text">
      <div class="snackbar-icon">
        <i class="fa-solid fa-circle-exclamation"></i>
      </div>
      <div class="snackbar-text">
        <div class="snackbar-heading">Upload failed</div>
        <div class="snackbar-body">File exceeds the 10 MB limit.</div>
      </div>
    </div>
    <button class="snackbar-close" aria-label="Dismiss">
      <i class="fa-solid fa-xmark"></i>
    </button>
  </div>
</div>

Minimal (No Icon, No Link, No Progress)

<div class="snackbar" role="status" aria-live="polite">
  <div class="snackbar-content">
    <div class="snackbar-icon-text">
      <div class="snackbar-text">
        <div class="snackbar-heading">Item deleted</div>
        <div class="snackbar-body">The record has been removed.</div>
      </div>
    </div>
    <button class="snackbar-close" aria-label="Dismiss">
      <i class="fa-solid fa-xmark"></i>
    </button>
  </div>
</div>

Tab Bar

A horizontal navigation element that shows users where they are in a multi-step process. Users can see completed steps, the current step, and remaining steps, and click any previous step to navigate back.

Overview

The Tab Bar is a linear, horizontal stepper that communicates progress through a multi-step workflow. Each tab represents one step. The selected (current) tab is visually distinguished with a bold label and an orange bottom border. Unselected tabs use regular-weight text with no bottom border. Two layout variants exist: Icons (each tab has an optional leading icon and a text label) and Numbers (each tab has a numeric prefix and a text label, no icon). Four interaction states apply per tab: Default, Hover, Focus, and Disabled.

Variants

Tab Item - Unselected

Regular-weight label, no bottom border highlight. Used for steps the user has not yet reached or for completed steps they can revisit.

Tab Item - Selected

Bold label with a 2px orange bottom border. Indicates the current active step in the process.