Design Tokens

Design tokens are the smallest building blocks of a design system. They represent design decisions as data, making it easy to maintain consistency across platforms and products.

Yle Design System’s design tokens are based on Yle’s parent brand in terms of user interface design. The parent brand’s visual identity is black and white, minimalist, and fresh, enabling clear presentation of diverse content across Yle’s main services, such as the Yle service and Areena.

What are Design Tokens?

Design tokens capture the visual attributes of a design system—colors, typography, spacing, shadows, and more—as named entities. Instead of hardcoding values like #00b4c8 or 16px, we use semantic names like --yds-color-yle-turquoise-50 or --yds-spacing-16.

• Consistency: Semantic names ensure uniform styling across all products
• Maintainability: Update a token value once, and it propagates everywhere
• Theming: Switch between light and dark themes by swapping token sets
• Cross-platform: Same design decisions, different platform implementations

Token Categories

Category	Description
Global Colors	Base color swatches with neutrals, brand colors, and other palettes
Theme Colors	Semantic tokens for UI: backgrounds, text, actions, and feedback
Spacing	Consistent spacing scale for margins, padding, and gaps
Border Radius	Corner rounding values for UI elements
Border	Border widths for UI elements
Shadows	Elevation and depth through box shadows
Typography	Font sizes, weights, and line heights
Transitions	Animation duration and easing values

Using Tokens

CSS Variables

All tokens are available as CSS custom properties:

.button {
  background-color: var(--yds-color-yle-turquoise-50);
  padding: var(--yds-spacing-8) var(--yds-spacing-16);
  border-radius: var(--yds-border-radius-medium);
  transition: background-color var(--yds-transition-duration-s) var(--yds-transition-easing-default);
}

JavaScript Constants

Import tokens directly in JavaScript/TypeScript:

import { defaultTheme, spacing, radius } from '@yleisradio/yds-core';

const styles = {
  backgroundColor: defaultTheme.BACKGROUND,
  padding: spacing.SPACING_16,
  borderRadius: radius.MEDIUM,
};

Styled Components

When using YdsThemeProvider, theme tokens are available via props.theme.yds in any styled component. The tokens automatically reflect the active theme:

import styled from 'styled-components';

const Card = styled.div`
  background-color: ${(props) => props.theme.yds.BACKGROUND};
  color: ${(props) => props.theme.yds.TEXT_DEFAULT};
  border: 1px solid ${(props) => props.theme.yds.BORDER_DEFAULT};
`;

Theming

The design system supports multiple themes. Semantic color tokens automatically adapt when the theme changes:

• Light theme: Default theme with light backgrounds
• Dark theme: Dark backgrounds with adjusted colors for accessibility
• Custom themes: Tietäjä and other product-specific themes

Using Theme Tokens

Use semantic theme tokens instead of base colors for UI elements. This ensures proper contrast and accessibility in both light and dark modes:

.card {
  /* ✅ Do: Use theme tokens */
  background-color: var(--yds-color-background);
  color: var(--yds-color-default-text);

  /* ❌ Don't: Use base colors for themed elements */
  background-color: var(--yds-color-white);
}

Applying Themes

In React, wrap your app (or any subtree) with YdsThemeProvider from @yleisradio/yds-components-react:

import { YdsThemeProvider } from '@yleisradio/yds-components-react';

export const App = () => (
  <YdsThemeProvider theme="light">
    <YourApp />
  </YdsThemeProvider>
);

The theme prop accepts 'light', 'dark', 'default', or a custom theme object. You can also nest providers to apply different themes to specific subtrees:

<YdsThemeProvider theme="light">
  <MainContent />
  <YdsThemeProvider theme="dark">
    <DarkSidebar />
  </YdsThemeProvider>
</YdsThemeProvider>

For plain HTML, import the theme CSS file and its variables are applied to :root automatically — no classes needed:

/* Light theme applied to :root */
@import '@yleisradio/yds-core/tokens/build/css/_theme-default.css';

To automatically switch to dark based on the user's OS preference, use the prefers-color-scheme variant alongside the default:

@import '@yleisradio/yds-core/tokens/build/css/_theme-default.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-default-prefers-dark.css';

To force a specific theme on a subtree, import the themed variants and add the corresponding class:

@import '@yleisradio/yds-core/tokens/build/css/_theme-light.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-dark.css';

<div class="yds-theme-light">Light theme content</div>
<div class="yds-theme-dark">Dark theme content</div>

Token Naming Convention

A design token is defined in the Figma Variables:

spacing/8

This gets converted to the following JSON:

{ "spacing": { "8": { "value": 8 } } }

Is available in each platform format as:

CSS

--yds-spacing-8: 8px;

SCSS

$yds-spacing-8: 8px;

JavaScript

import { spacing } from '@yleisradio/yds-core';

spacing.SPACING_8; // sometimes prefixed with CATEGORY_ as number mustn't start JS variable name

For theme colors, token names are semantic (e.g., background, default-text) rather than descriptive of the color value itself, so they remain meaningful across themes.