Skip to main content

Get started with yds-components-react 3.0

Install the packages, put design tokens on :root, and render a component. styled-components is not required. This page is for applications that consume @yleisradio/yds-components-react. Component APIs, tokens, and usage examples elsewhere on this site do not require installing the package.

Coming from 2.x? Breaking changes in React package 3.0 is the upgrade guide. If the app keeps styled-components as its own styling library, also see Using styled-components with YDS 3.0.

1. Install​

npm install @yleisradio/yds-core @yleisradio/yds-icons-react @yleisradio/yds-components-react

2. Load Yle Next​

Components expect the Yle Next variable font. Simplest way to get it is to add the design-system CDN stylesheet in <head>:

<link rel="stylesheet" href="https://design-system.cdn.yle.fi/fonts/fonts.css" />

That file is the supported entry point for every font family the design system ships. It can grow as more styles are added.

To write your own @font-face rules, the variable files are:

To host the fonts locally in the app instead of loading it from the CDN, install @yleisradio/yds-fonts and import the necessary files from the package:

npm install @yleisradio/yds-fonts

3. Put tokens on :root​

Components read var(--yds-color-*), spacing, radius, typography and shadow variables. Those must exist on a DOM ancestor — for the whole app, import them once as global CSS.

/* yds-tokens.css */
@import '@yleisradio/yds-core/tokens/build/css/_border-radius.css';
@import '@yleisradio/yds-core/tokens/build/css/_spacing.css';
@import '@yleisradio/yds-core/tokens/build/css/_typography.css';
@import '@yleisradio/yds-core/tokens/build/css/_shadow-default.css';
@import '@yleisradio/yds-core/tokens/build/css/_shadow-default-prefers-dark.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-default.css';
@import '@yleisradio/yds-core/tokens/build/css/_theme-default-prefers-dark.css';
import './yds-tokens.css';

Import this file at the top of the app entry, before any component that pulls in YDS CSS. Missing a token file shows up as unstyled components, not a JavaScript error.

Alternatively, YdsThemeProvider can wrap a subtree (or, as a migration step, :root) instead of importing these files.

App themeToken files
Light, following the OSThe list above
Always lightOmit the two *-prefers-dark files
Always dark_shadow-default-dark.css and _theme-default-dark.css instead of the light default + prefers-dark pair
Switch between light and dark_theme-light.css / _theme-dark.css and _shadow-light.css / _shadow-dark.css — use .yds-theme-light and .yds-theme-dark on the application root

Wrappers: development vs production​

If a parent page already loads the same files, do not import them again.

Yle apps often sit inside a wrapper. Who owns :root then depends on the environment:

EnvironmentWho sets tokens
ProductionThe wrapper usually already delivers the page theme. Skip the :root imports so the same variables are not defined twice.
DevelopmentThere is often no wrapper. Import the token CSS yourself (the list above) so components are not unstyled.

If the app needs its own color or shadow tokens while the wrapper still owns the rest of the page, do not write them to :root — that would override the host. Inject a *CssFragment from @yleisradio/yds-core and scope it to the application ID the wrapper puts on your root:

import { darkThemeCssFragment, darkShadowCssFragment } from '@yleisradio/yds-core';

const applicationId = 'your-application-id';

const style = document.createElement('style');
style.textContent = `#${applicationId} {
  ${darkThemeCssFragment}
  ${darkShadowCssFragment}
}`;
document.head.appendChild(style);

Preset fragments: lightThemeCssFragment, darkThemeCssFragment, lightShadowCssFragment, darkShadowCssFragment. For a generated Theme, use themeToCssFragment. themeToCss from @yleisradio/yds-components-react wraps the same fragments in a selector if you prefer not to concatenate them by hand.

What about YdsThemeProvider?​

You no longer need YdsThemeProvider around the app if the theme is served by the methods above. It can still be used as an alternative way to set up a theme wrapper. Details: YdsThemeProvider.

4. Let the bundler compile CSS Modules​

Components import their own *.module.css files. Process those as CSS Modules (including under node_modules). Process every other .css file from this package and from @yleisradio/yds-core as global CSS — token files must not be hashed.

Component styles live in @layer yds. An unlayered global reset (* { margin: 0; padding: 0 }) wins over that layer and strips spacing. Breaking changes — Global resets has the layer recipe.

5. Render a component​

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

<Button variant="primary" text="Click me" />;

If the button has no color or padding, the bundler is not compiling CSS Modules from node_modules, or the token CSS is not on :root. Check DevTools: html should list --yds-color-* variables, and the button's padding should come from a rule labelled @layer yds.

6. Use tokens in your own styles​

.card {
  background: var(--yds-color-background-variant);
  color: var(--yds-color-text-default);
  padding: var(--yds-spacing-16);
  border-radius: var(--yds-border-radius-medium);
  box-shadow: var(--yds-shadow-md);
}

In JavaScript, defaultTheme from @yleisradio/yds-core is the same values, typed, with a light fallback:

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

defaultTheme.BACKGROUND; // 'var(--yds-color-background, #ffffff)'

Token catalogue: Design tokens.

Without React​

Import the bundled stylesheet for CDN delivery or prototypes. Class names are stable (yds-Button, yds-Button__variant_primary). Do not import all.css together with the React components — that duplicates styles.

import '@yleisradio/yds-components-react/styles/all.css';

Naming: CSS class naming conventions.