Design Tokens

Design tokens are the building blocks of your theme and thread through every Web Awesome component, giving your project a cohesive look and feel. They control everything from typography and color to spacing and borders.

Using Design Tokens

Link to This Section

Design tokens are CSS custom properties prefixed with --wa-. Use them in your own stylesheets by wrapping the token name in the CSS var() function and assigning it to a property:

.branded-container {
  background-color: var(--wa-color-brand-fill-normal);
  border: var(--wa-border-width-s) var(--wa-border-style) var(--wa-color-brand-border-normal);
  color: var(--wa-color-brand-on-normal);
}

You can also use design tokens with inline styles:

<span style="
  background-color: var(--wa-color-brand-fill-normal);
  color: var(--wa-color-brand-on-normal);
"></span>

Customizing Design Tokens

Link to This Section

Overriding a design token updates every component and style that references it, making it a breeze to style and restyle your project. To customize a token, set its value in your styles. Setting tokens on :root applies them globally across your entire project:

:root {
  --wa-font-family-body: 'Inter', sans-serif;
  --wa-border-width-scale: 1.5; /* scales all border widths proportionally */
}

To customize a token that adapts to light and dark mode, scope the token to .wa-light, .wa-dark, and, optionally, .wa-invert:

:root,
.wa-light,
.wa-dark .wa-invert {
  --wa-color-surface-default: var(--wa-color-neutral-95);
}

.wa-dark,
.wa-invert {
  --wa-color-surface-default: var(--wa-color-neutral-05);
}

You can also scope tokens to a subtree rather than :root, which allows you to theme a single section or element differently from the rest:

*:state(user-invalid),
*:user-invalid {
  --wa-color-focus: var(--wa-color-danger-60);
  --wa-form-control-border-color: var(--wa-color-danger-border-normal);
  --wa-form-control-label-color: var(--wa-color-danger-on-quiet);
}