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¶
--wa-color-red--wa-color-orange--wa-color-yellow--wa-color-green--wa-color-cyan--wa-color-blue--wa-color-indigo--wa-color-purple--wa-color-pink--wa-color-graySemantic variants¶
--wa-color-brand--wa-color-neutral--wa-color-success--wa-color-warning--wa-color-dangerColor token reference¶
| Token or pattern | Purpose |
|---|---|
--wa-color-{hue}-{tint} | 10 hues × 11 tints, 95 (lightest) through 05 (darkest). |
--wa-color-{hue} / --wa-color-{hue}-on | Core hue and its readable foreground. |
--wa-color-{variant}-{tint} | Semantic palettes: brand, neutral, success, warning, danger. |
--wa-color-{variant} / --wa-color-{variant}-on | Core variant and its paired foreground. |
| `--wa-color-{variant}-{fill | border |
--wa-color-surface-raised / --wa-color-surface-default / --wa-color-surface-lowered | Surface elevation levels. |
--wa-color-surface-border | Surface boundaries. |
--wa-color-text-normal / --wa-color-text-quiet / --wa-color-text-link | Text hierarchy and links. |
--wa-color-overlay-modal / --wa-color-overlay-inline | Backdrops and inline overlays. |
--wa-color-shadow / --wa-color-focus | Shadow tint and focus-ring color. |
--wa-color-mix-hover / --wa-color-mix-active | Hover/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.
| Group | Available 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.
| Token | Purpose |
|---|---|
--wa-border-style | Default border line style. |
--wa-border-width-scale | Global border thickness multiplier. |
--wa-border-width-s / --wa-border-width-m / --wa-border-width-l | Small, medium, and large stroke widths. |
--wa-border-radius-scale | Global corner rounding multiplier. |
--wa-border-radius-s / --wa-border-radius-m / --wa-border-radius-l | Size-based corner rounding. |
--wa-border-radius-pill / --wa-border-radius-circle / --wa-border-radius-square | Fixed 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.
| Token | Purpose |
|---|---|
--wa-shadow-s / --wa-shadow-m / --wa-shadow-l | Ready-to-use small, medium, large shadows. |
--wa-shadow-offset-x-scale / `--wa-shadow-offset-x-{s | m |
--wa-shadow-offset-y-scale / `--wa-shadow-offset-y-{s | m |
--wa-shadow-blur-scale / `--wa-shadow-blur-{s | m |
--wa-shadow-spread-scale / `--wa-shadow-spread-{s | m |
--wa-color-shadow | Shared 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.
| Token | Purpose |
|---|---|
--wa-focus-ring-style | Outline line style. |
--wa-focus-ring-width | Outline stroke width. |
--wa-focus-ring | Complete outline shorthand. |
--wa-focus-ring-offset | Gap between control and ring. |
--wa-color-focus | Theme-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.
.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.
| Group | Properties |
|---|---|
| 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:
This card inherits shared panel border and radius tokens.
The callout shares panel styling with the card.
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.