Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Design Tokens

Design tokens are Web Awesome’s theme-aware CSS custom properties. They control the visual language shared by components and ordinary HTML: color, typography, space, borders, shadows, focus, transitions, and component groups. This page illustrates the eight families from Web Awesome 3.14.0, the version pinned by SoftCloud, using the existing site stylesheet and MyST documentation primitives.

Source: Web Awesome design token index · Theming documentation · Component catalog.

Palettes, variants, themed surfaces, and foregrounds.

Font families, type scale, weights, and line height.

Consistent spacing from 3xs to 5xl.

Border strokes, radii, and shape.

Elevation, offsets, blur, and spread.

Keyboard focus outlines and offset.

Durations, easing, and reduced-motion support.

Shared form, button, panel, and tooltip styling.

Color

Web Awesome separates its 10-hue palette, five semantic variants, and role-based surface/content colors. Each hue has 11 tints: 95, 90, 80, 70, 60, 50, 40, 30, 20, 10, 05. For text on core fills, always pair a core token with its matching -on token rather than assuming black or white.

Core palette colors

Aa
Red--wa-color-red
Aa
Orange--wa-color-orange
Aa
Yellow--wa-color-yellow
Aa
Green--wa-color-green
Aa
Cyan--wa-color-cyan
Aa
Blue--wa-color-blue
Aa
Indigo--wa-color-indigo
Aa
Purple--wa-color-purple
Aa
Pink--wa-color-pink
Aa
Gray--wa-color-gray

Semantic variants

Aa
Brand--wa-color-brand
Aa
Neutral--wa-color-neutral
Aa
Success--wa-color-success
Aa
Warning--wa-color-warning
Aa
Danger--wa-color-danger

Color token reference

Token or patternPurpose
--wa-color-{hue}-{tint}10 hues × 11 tints, 95 (lightest) through 05 (darkest).
--wa-color-{hue} / --wa-color-{hue}-onCore hue and its readable foreground.
--wa-color-{variant}-{tint}Semantic palettes: brand, neutral, success, warning, danger.
--wa-color-{variant} / --wa-color-{variant}-onCore variant and its paired foreground.
`--wa-color-{variant}-{fillborder
--wa-color-surface-raised / --wa-color-surface-default / --wa-color-surface-loweredSurface elevation levels.
--wa-color-surface-borderSurface boundaries.
--wa-color-text-normal / --wa-color-text-quiet / --wa-color-text-linkText hierarchy and links.
--wa-color-overlay-modal / --wa-color-overlay-inlineBackdrops and inline overlays.
--wa-color-shadow / --wa-color-focusShadow tint and focus-ring color.
--wa-color-mix-hover / --wa-color-mix-activeHover/pressed color mixtures.

The wa-brand-{hue} and related wa-{variant}-{hue} classes on the document root select a palette hue for a semantic variant. Accessible contrast depends on the resolved pair, not merely the hue name.

.status-success {
  background: var(--wa-color-success-fill-normal);
  color: var(--wa-color-success-on-normal);
  border: var(--wa-border-width-s) var(--wa-border-style)
    var(--wa-color-success-border-normal);
}

Upstream: Color token reference.

Typography

Typography tokens cover role-specific font families, a responsive-friendly size scale, line heights, weights, and link decoration. Font-size tokens are based on rem and scale through --wa-font-size-scale; component previews therefore reflect the current theme rather than a fixed pixel chart.

Body — Sphinx of black quartz, judge my vow.

Heading — Sphinx of black quartz, judge my vow.

Code — Sphinx of black quartz, judge my vow.

Longform — Sphinx of black quartz, judge my vow.

GroupAvailable properties
Font family--wa-font-family-body, --wa-font-family-heading, --wa-font-family-code, --wa-font-family-longform
Font size--wa-font-size-scale, --wa-font-size-3xs, --wa-font-size-2xs, --wa-font-size-xs, --wa-font-size-s, --wa-font-size-m, --wa-font-size-l, --wa-font-size-xl, --wa-font-size-2xl, --wa-font-size-3xl, --wa-font-size-4xl, --wa-font-size-5xl, --wa-font-size-smaller, --wa-font-size-larger
Font weight--wa-font-weight-light, --wa-font-weight-normal, --wa-font-weight-semibold, --wa-font-weight-bold, --wa-font-weight-body, --wa-font-weight-heading, --wa-font-weight-code, --wa-font-weight-longform, --wa-font-weight-action
Line height--wa-line-height-condensed, --wa-line-height-normal, --wa-line-height-expanded
Link decoration--wa-link-decoration-default, --wa-link-decoration-hover

For long-form text, choose an appropriate font family and --wa-line-height-normal (or expanded); do not reduce paragraph leading just to fit a sample.

.documentation-lead {
  font-family: var(--wa-font-family-longform);
  font-size: var(--wa-font-size-l);
  line-height: var(--wa-line-height-expanded);
  color: var(--wa-color-text-normal);
}

Upstream: Typography token reference.

Space

The space scale uses rem units and the multiplier --wa-space-scale. Bars below take their lengths from the active tokens; the smallest tokens may render as narrow marks on dense displays.

--wa-space-3xs
--wa-space-2xs
--wa-space-xs
--wa-space-s
--wa-space-m
--wa-space-l
--wa-space-xl
--wa-space-2xl
--wa-space-3xl
--wa-space-4xl
--wa-space-5xl

--wa-content-spacing is the semantic default spacing between top-level content blocks. Prefer semantic layout relationships instead of applying a single arbitrary gap everywhere.

.card-stack {
  display: grid;
  gap: var(--wa-space-l);
  padding: var(--wa-space-m);
}

Upstream: Space token reference.

Borders

Borders use scale-controlled stroke widths and radii, plus fixed shape aliases for pills, circles, and squares. These examples use the token values directly.

Small
Medium
Large
Pill
TokenPurpose
--wa-border-styleDefault border line style.
--wa-border-width-scaleGlobal border thickness multiplier.
--wa-border-width-s / --wa-border-width-m / --wa-border-width-lSmall, medium, and large stroke widths.
--wa-border-radius-scaleGlobal corner rounding multiplier.
--wa-border-radius-s / --wa-border-radius-m / --wa-border-radius-lSize-based corner rounding.
--wa-border-radius-pill / --wa-border-radius-circle / --wa-border-radius-squareFixed shape tokens; circle requires square dimensions.

--wa-border-width-scale and --wa-border-radius-scale can adjust component appearance globally. Shape tokens (such as pill) are not scaled like size-based radii.

Upstream: Borders token reference.

Shadows

Three ready-to-use shadows are composed from smaller offset, blur, and spread variables plus --wa-color-shadow. Use shadow tokens for elevation; do not invent a separate page-specific shadow scale.

Small
Medium
Large
TokenPurpose
--wa-shadow-s / --wa-shadow-m / --wa-shadow-lReady-to-use small, medium, large shadows.
--wa-shadow-offset-x-scale / `--wa-shadow-offset-x-{sm
--wa-shadow-offset-y-scale / `--wa-shadow-offset-y-{sm
--wa-shadow-blur-scale / `--wa-shadow-blur-{sm
--wa-shadow-spread-scale / `--wa-shadow-spread-{sm
--wa-color-shadowShared shadow color.

The shadow shorthand can be inset: box-shadow: inset var(--wa-shadow-s);. Larger effects may be less appropriate in dense documentation layouts.

Upstream: Shadows token reference.

Focus

Keyboard focus must remain visible in both light and dark themes. Web Awesome composes its focus-ring style, width, and --wa-color-focus into a reusable shorthand. Use Tab to focus the native controls below; this preview works without JavaScript.

Example label Tab to focus this field Focusable button
TokenPurpose
--wa-focus-ring-styleOutline line style.
--wa-focus-ring-widthOutline stroke width.
--wa-focus-ringComplete outline shorthand.
--wa-focus-ring-offsetGap between control and ring.
--wa-color-focusTheme-specific focus-ring color.
.custom-control:focus-visible {
  outline: var(--wa-focus-ring);
  outline-offset: var(--wa-focus-ring-offset);
}

Do not remove a focus outline without providing an equivalent high-contrast alternative.

Upstream: Focus token reference.

Transitions

Transition duration tokens are --wa-transition-fast, --wa-transition-normal, and --wa-transition-slow. --wa-transition-easing specifies the shared timing function. Hover or keyboard-focus each button to compare its response; when reduced motion is requested, the animation is disabled.

Fast Normal Slow
.interactive-surface {
  transition: background-color var(--wa-transition-normal)
    var(--wa-transition-easing);
}
@media (prefers-reduced-motion: reduce) {
  .interactive-surface { transition: none; }
}

Upstream: Transitions token reference.

Component Groups

Group-level variables share visual decisions across related components. Unlike individual wa-* component-specific CSS properties, these act on a family of controls without duplicating overrides. Not every form control consumes every form-control token.

GroupProperties
Form controls (surface)--wa-form-control-background-color, --wa-form-control-border-color, --wa-form-control-border-style, --wa-form-control-border-width, --wa-form-control-border-radius, --wa-form-control-activated-color
Form controls (text)--wa-form-control-label-color, --wa-form-control-label-font-weight, --wa-form-control-label-line-height, --wa-form-control-value-color, --wa-form-control-value-font-weight, --wa-form-control-value-line-height, --wa-form-control-hint-color, --wa-form-control-hint-font-weight, --wa-form-control-hint-line-height, --wa-form-control-placeholder-color
Form controls (required & sizing)--wa-form-control-required-content, --wa-form-control-required-content-color, --wa-form-control-required-content-offset, --wa-form-control-padding-block, --wa-form-control-padding-inline, --wa-form-control-height, --wa-form-control-toggle-size
Buttons--wa-button-transform-hover, --wa-button-transform-active
Panels--wa-panel-border-style, --wa-panel-border-width, --wa-panel-border-radius
Tooltips--wa-tooltip-arrow-size, --wa-tooltip-background-color, --wa-tooltip-border-color, --wa-tooltip-border-style, --wa-tooltip-border-width, --wa-tooltip-border-radius, --wa-tooltip-content-color, --wa-tooltip-font-size, --wa-tooltip-line-height

SSR panel and button atoms

These use SoftCloud’s existing typed {wa-card}, {wa-callout}, and {wa-button} MyST directives (real Lit SSR/Declarative Shadow DOM), not a second component renderer:

Panel example

This card inherits shared panel border and radius tokens.

Token-aware action

Interactive form controls

The native fieldset is the no-JavaScript reference; the Web Awesome preview beneath it enhances the example when its self-hosted modules load.

Native form reference

Email person@example.org [ ] Receive updates

Copyable HTML using the same existing atomic components:

<wa-input label="Email" type="email" placeholder="person@example.org"></wa-input>
<wa-select label="Environment" value="production">
  <wa-option value="development">Development</wa-option>
  <wa-option value="production">Production</wa-option>
</wa-select>
<wa-checkbox>Receive updates</wa-checkbox>
<wa-button variant="brand">Submit</wa-button>

Related catalog pages: Input, Select, Checkbox, Button, Card, and Callout.

Upstream: Component group tokens.

Putting tokens together

A single portable CSS rule can use several families without redefining their values:

.feature-panel {
  background: var(--wa-color-surface-raised);
  color: var(--wa-color-text-normal);
  border: var(--wa-border-width-s) var(--wa-border-style)
    var(--wa-color-surface-border);
  border-radius: var(--wa-border-radius-l);
  box-shadow: var(--wa-shadow-s);
  padding: var(--wa-space-l);
  font-family: var(--wa-font-family-body);
  line-height: var(--wa-line-height-normal);
  transition: box-shadow var(--wa-transition-normal)
    var(--wa-transition-easing);
}
@media (prefers-reduced-motion: reduce) {
  .feature-panel { transition: none; }
}

MyST {grid}, {card}, and standard Markdown remain the default for documentation structure. Reuse typed SSR directives for the four integrated Web Awesome primitives; use the existing {anywidget} when genuine interaction is required. Every preview must retain readable content when scripts are unavailable.

Token names and intent were checked against the official Web Awesome 3.x reference. Exact computed values are theme-dependent; use browser developer tools to inspect your chosen theme instead of copying a screenshot’s numeric colors.