CSC Design System v4.0.1
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

Customization

Everything about making the design system yours: re-branding with theme seeds, dark mode, the semantic tokens, restyling components through their parts, setting app-wide prop defaults, and using the tokens in your own Tailwind build.

Three axes of customization

Customization splits along three independent axes. Colours flow through the design tokens: you hand the library one seed colour per family, it regenerates the full palette ramp, and every semantic token — in both light and dark mode — follows automatically. You never restyle a component's colours directly. Structure flows through named parts: each component exposes a curated set of ::part() regions (root, content, …), and that part set is the component's customization contract. Behaviour presets flow through app-wide prop defaults: applyDefaults sets a preference prop — labels on top, hidden hint rows, the texts a component speaks — for every instance of a tag, and any instance can still override it. Per-component CSS custom properties like --c-button-background-color do not exist in this library — if you are upgrading from @cscfi/csc-ui, see the migration guide.

Re-brand with theme seeds

applyTheme takes one step-500 seed colour per family and regenerates that family's whole 50–950 ramp (an OKLCH perceptual curve, anchored so step 500 reproduces your seed exactly). Because the semantic tokens resolve through the ramp, a single seed re-brands every component in both theme modes. The eight chromatic families are themable: primary, secondary, accent, success, info, warning, error, and link. The neutrals and the semantic role→step mappings are hand-tuned for WCAG AA contrast and deliberately not overridable. Validation is fail-loud: an unknown family name or an unparseable colour throws, so a typo cannot silently ship the default brand. Try it live below — the playground re-seeds this whole site.

import {
  applyTheme,
  resetTheme,
} from '@cscfi/csc-ui';

// One step-500 seed per family; the full 50–950 ramp and both
// light and dark modes regenerate from it at runtime.
applyTheme({ primary: '#006efd', accent: '#7c3aed' });

// Later calls merge with earlier ones — primary and accent stay overridden.
applyTheme({ error: '#d61f26' });

// Restore selected families to the defaults — or everything: resetTheme().
resetTheme(['accent']);

Server rendering & first paint

applyTheme needs a DOM, so on the server — and to avoid a flash of the default brand before your first client-side call — use themeToCss instead. It is a pure function that returns a :root { … } rule as a string, safe to render into <head> during SSR. In Nuxt, inject it with useHead.

app.vue
import { themeToCss } from '@cscfi/csc-ui';

// Rendered into <head> at SSR time — the brand is right on first paint.
useHead({
  style: [{ innerHTML: themeToCss({ primary: '#006efd' }) }],
});

Dark mode

Components follow the OS light/dark preference by default. To pin a mode explicitly, set data-theme="light" or "dark" on <html> — the explicit attribute always wins over the OS preference; removing it goes back to following the OS. The same attribute works on any element, not just <html>. An element carrying data-theme opens a mode scope: it and everything inside it resolve in that mode, whatever the rest of the page is doing. Scopes nest, and the nearest one wins. Only light and dark pin a mode — any other value is ignored, so a data-theme your own theming system already sets will not pull components out of the surrounding mode. The switching happens in the semantic-token layer: every role token (surface, on-surface, border, …) resolves to a different palette step per mode, so components and any UI you build on the tokens flip together. Seeds and modes compose — a re-branded ramp feeds both modes, so applyTheme needs no dark-mode variant, and a seeded ramp feeds every scope. A scope can also be relative. An element carrying data-theme-invert resolves every role in the opposite mode to the one it sits in — dark inside a light page, light inside a dark one — so a region that must always stand apart from its surroundings needs no per-page variant. Inverting scopes nest like pinned ones, so inverting twice is back in the surrounding mode, and a data-theme on the same element wins over the inversion. On <html> it means the opposite of the OS preference. The attribute is presence-only, like hidden: data-theme-invert="false" still inverts, so remove it to stop. A mode scope re-points colours; it paints nothing. Give a container bg-surface and text-on-surface (or the var(--c-…) equivalents) to make it draw the mode it pins — otherwise a colour inherited from outside the scope keeps the outer mode's ink. Every scope publishes the mode it resolved as --c-mode (light or dark). Read it from JS, or style-query it from your own CSS with @container style(--c-mode: dark) { … }, instead of duplicating the data-theme selectors.

<!-- Pin a mode for the whole app; unset = follow the OS preference. -->
<html data-theme="dark">
Pin a mode for part of the page
<!-- A permanently dark panel on a light page. The scope re-points the
     tokens; bg-surface/text-on-surface make the panel paint them. -->
<section data-theme="dark" class="bg-surface text-on-surface">
  <c-card>
    <c-card-content>Always dark, whatever the user picked.</c-card-content>
  </c-card>

  <!-- Scopes nest: the nearest one wins. -->
  <aside data-theme="light" class="bg-surface text-on-surface">Always light.</aside>
</section>

<!-- A single component works too — the host is a scope like any element. -->
<c-button data-theme="dark">Dark button</c-button>
Invert the surrounding mode
<!-- Opposite of whatever the page is: dark when the page is light, light
     when it is dark. Paint opt-in is the same as for a pinned scope. -->
<section data-theme-invert class="bg-surface text-on-surface">
  <c-card>
    <c-card-content>Always the opposite of the page.</c-card-content>
  </c-card>

  <!-- Inverting twice is back in the page's mode. -->
  <aside data-theme-invert class="bg-surface text-on-surface">Back to the page's mode.</aside>
</section>

<!-- At the root it means the opposite of the OS preference. -->
<html data-theme-invert>
Runtime toggle with a stored choice
const setMode = (mode: 'light' | 'dark' | 'system') => {
  if (mode === 'system') {
    document.documentElement.removeAttribute('data-theme');
    localStorage.removeItem('theme');
  } else {
    document.documentElement.dataset.theme = mode;
    localStorage.setItem('theme', mode);
  }
};
index.html — restore the choice before first paint
<script>
  // Inline in <head>, so a stored mode applies before anything renders.
  const theme = localStorage.getItem('theme');
  if (theme === 'light' || theme === 'dark') {
    document.documentElement.dataset.theme = theme;
  }
</script>
Follow the mode in effect for an element
import { chartSlotsHex, observeThemeMode } from '@cscfi/csc-ui';

// Resolves the mode in effect where the element sits — a pinned or inverting
// scope, else the OS preference — then follows it: a data-theme flip on any
// ancestor, or the OS preference changing while no scope pins a mode. Fires
// once immediately, so this is the whole wiring.
const stop = observeThemeMode(chartEl, (mode) => {
  chart.setOption({ color: chartSlotsHex[mode] });
});
Overriding a role token? Scope it too
/* A mode scope — pinned or inverting — re-declares every role on
   itself, and an element's own declaration beats an inherited one, so a
   :root-only override stops applying inside a scope. Cover all three. */
:root,
[data-theme],
[data-theme-invert] {
  --c-surface: #101418;
}

/* Seed overrides (applyTheme) need no such care: they set palette tokens
   that the roles still point at, so they reach every scope. */

Semantic token reference

The semantic tokens are the palette every component authors against — and the vocabulary your own UI can share. In CSS they are custom properties with a --c- prefix (var(--c-surface)); through the Tailwind theme export the same roles appear as unprefixed colour utilities. Each token resolves to a different palette step per theme mode, and the steps themselves regenerate when you seed a family — so anything built on these tokens follows both the mode and the brand automatically. The swatches below are live: flip the theme toggle or use the playground above and watch them move.

Surface ladder

TokenSwatchLightDarkPurpose
--c-surfacewhiteslate-800Default page and app background.
--c-surface-raisedwhiteslate-800Cards and other blocks lifted off the page.
--c-surface-overlaywhiteslate-700Floating layers: menus, popovers, modals.
--c-surface-mutedtertiary-100slate-850Subdued fills: wells, code captions, table stripes.
--c-surface-sunkenprimary-100slate-900Recessed areas set below the page.

Foregrounds

TokenSwatchLightDarkPurpose
--c-on-surfaceprimary-900slate-100Default body text and icons.
--c-on-surface-mutedtertiary-600slate-300Secondary text.
--c-on-surface-fainttertiary-600slate-400Hints, captions, and de-emphasized labels.
--c-on-surface-disabledtertiary-300slate-500Text of disabled options, days and buttons.
--c-on-surface-sunkenprimary-700slate-100Text on the sunken surface.
--c-on-surface-errorerror-500error-300Error text on a surface: messages and required marks. Lighter than the error fill in dark mode.

Border & focus

TokenSwatchLightDarkPurpose
--c-bordertertiary-200slate-700Opaque edges for frames that have another cue: card frames, toolbar edge, table grid lines.
--c-dividerblack @ 12%white @ 12%Translucent hairline ink: separators and load-bearing control frames; reads on every surface.
--c-border-strongtertiary-600slate-400Emphasized borders, e.g. resting form-field outlines.

Inverse & scrim

Mode-invariant: these resolve to the same value in light and dark.

TokenSwatchLightDarkPurpose
--c-inverse-surfacewhitewhiteSurface for inverted component variants.
--c-inverse-onwhitewhiteForeground on inverted variants.
--c-inverse-primaryprimary-600primary-600Primary role inside inverted variants.
--c-inverse-errorerror-600error-600Error role inside inverted variants.
--c-inverse-secondarysecondary-600secondary-600Secondary label on an inverted filled button.
--c-inverse-successsuccess-700success-700Success label on an inverted filled button.
--c-inverse-infoinfo-600info-600Info label on an inverted filled button.
--c-inverse-warningwarning-800warning-800Warning label on an inverted filled button.
--c-scrimblackblackBackdrop behind modal layers (applied with opacity).

Role tokens

Each of the eight role families — primary, secondary, accent, success, info, warning, error, link — exposes the same six tokens. The palette step behind each one is hand-tuned per family and mode, so the matrix below shows the live values instead of a step table.

Token patternPurpose
--c-<role>The solid role colour.
--c-<role>-hoverHover state of the solid colour.
--c-on-<role>Text and icons on the solid colour.
--c-<role>-subtleTinted background fill.
--c-<role>-subtle-hoverHover state of the tinted fill.
--c-on-<role>-subtleText and icons on the tinted fill.
Family<role><role>-hoveron-<role><role>-subtle<role>-subtle-hoveron-<role>-subtle
primary
secondary
accent
success
info
warning
error
link

Restyle with ::part()

For anything beyond colours — spacing, radii, typography, layout — target a component's named parts with the CSS ::part() selector. The parts a component exposes are a curated contract: each component page lists them in its "CSS parts" table, and those names are stable API. Parts reach through the shadow boundary, so ordinary stylesheet rules work; there is nothing to configure. Keep colours inside part rules on the design tokens so your overrides still follow theme mode and brand seeds. Parts nested in inner components are forwarded on demand under a <child>-<part> naming convention — if a region you need is missing, request a part rather than working around the shadow root.

/* Restyle via named parts; keep colours on the tokens. */
c-button::part(root) {
  border-radius: 4px;
  background: var(--c-primary);
}

c-button::part(root):hover {
  background: var(--c-primary-hover);
}

Typography

Components draw in your page's typography. The typeface, line height and font features you set on body reach every component and the content you slot into it, as they reach native elements: c-main's page, a card's body and a select's option list alike. The library ships no font and no font token, so load your typeface and set it on body. On a page that sets no font, components fall back to the browser default, like any other element. Components pin type only where their design calls for it, such as a button label's size or an alert's text. To give one component another typeface, set font-family on its c-* element. Your rule outranks the component's own and reaches the components nested inside it.

/* Every component, and what you slot into it, inherits this. */
body {
  font-family: 'Noto Sans', sans-serif;
  line-height: 1.5;
}

/* One component in another typeface, nested components included. */
c-select {
  font-family: 'museo-sans', sans-serif;
}

App-wide prop defaults

Some props are preferences rather than per-instance data: whether labels sit on top of fields, whether the hint row is hidden, the field size, how many rows a list shows, the texts a component speaks. applyDefaults sets such a prop once for every instance of a tag, so an app decides them in one place instead of on every element. Only defaultable props take part — each component page marks them with an "app default" badge in its Properties table, and TypeScript accepts nothing else. A prop resolves instance value → app default → built-in default, so an explicit attribute or property on an element always wins, and later calls merge with earlier ones. The registry is live: mounted elements re-render when the defaults change, which makes runtime language switching a single texts call. An object prop such as texts is stored whole and merged key by key with the built-in strings, so a partial translation keeps the English fallbacks. Validation is fail-loud: an unknown tag or a prop that is not defaultable throws. The inner c-input the fields compose is not covered in this release — set the defaults on the field component you use. Try it live below: the demo fields follow the toggles, and the defaults are cleared again when you leave the page.

import {
  applyDefaults,
  resetDefaults,
} from '@cscfi/csc-ui';

// Every text field labels on top; every select shows five rows before the peek.
applyDefaults({
  'c-text-field': { labelOnTop: true },
  'c-select': { itemsPerPage: 5 },
});

// Later calls merge with earlier ones — the text-field default stays. One
// texts object translates every select; a per-instance texts still wins key by key.
applyDefaults({
  'c-select': {
    texts: { clearSelection: 'Tyhjennä valinta', toggleOptions: 'Näytä vaihtoehdot' },
  },
});

// An instance overrides its app default the usual way:
//   <c-text-field label-on-top="false">   or   field.labelOnTop = false

// Clear one key (undefined), one tag, or everything.
applyDefaults({ 'c-select': { itemsPerPage: undefined } });
resetDefaults(['c-select']);
resetDefaults();
main.ts
import { watch } from 'vue';
import { applyDefaults, defineCustomElements } from '@cscfi/csc-ui';

import { locale, messages } from './i18n';

defineCustomElements();

// The registry is live, so a locale change re-translates every mounted field.
watch(
  locale,
  (code) => applyDefaults({ 'c-select': { texts: messages[code].select } }),
  { immediate: true },
);

Tailwind theme export

If your app uses Tailwind v4, the library ships its semantic roles as a Tailwind theme export: @cscfi/csc-ui/css/tailwind-theme.css. It is a Tailwind v4 @theme mapping, not a standalone stylesheet — it maps utility names onto the --c-* custom properties, so it must be paired with tokens.css (which you are already loading for the components). Only the semantic roles are exported, by design: raw palette-step utilities would resolve to the same colour in both modes and silently break dark mode. If you genuinely need a raw step, reference its custom property (var(--c-primary-600)) directly — it reads as the escape hatch it is. To drop Tailwind's own default palette and keep the design-system roles only, reset it with --color-*: initial in your own @theme block.

app.css
@import 'tailwindcss';

/* Token definitions (required) + the @theme mapping onto them. */
@import '@cscfi/csc-ui/css/tokens.css';
@import '@cscfi/csc-ui/css/tailwind-theme.css';
<!-- Semantic utilities follow theme mode and brand seeds automatically. -->
<div class="rounded-lg border border-border bg-surface-raised p-4 text-on-surface">
  <h2 class="text-on-surface">Card title</h2>
  <p class="text-on-surface-muted">Body copy.</p>
</div>