Releases · datocms/plugins-sdk

03 Jun 16:24

stefanoverna

v2.2.1

93e5259

v2.2.1 — Semantic color tokens & dark-mode support Latest

Latest

What's new

This release ships across both datocms-plugin-sdk and datocms-react-ui.

Semantic color tokens (`ctx.cssDesignTokens`)

The plugin context now exposes a cssDesignTokens field — a Record<string, string> mapping CSS custom property names to their resolved values (e.g. { '--color--surface': '…', '--color--primary--surface': '…' }). The host computes these for the user's active theme, light or dark per their preference.

If you use datocms-react-ui, Canvas injects these onto the canvas for you. Otherwise apply them yourself:

Object.assign(document.documentElement.style, ctx.cssDesignTokens)

Color scheme awareness (`ctx.colorScheme`)

ctx.colorScheme is 'light' or 'dark' (the host resolves 'system' for you). On every ctx update the SDK reflects this onto document.documentElement:

data-color-scheme="light" / data-color-scheme="dark" attribute for explicit CSS selectors
The color-scheme CSS property so light-dark() resolves correctly and native controls match the active scheme

Dark-mode support in `datocms-react-ui`

All built-in components (Button, Dropdown, Section, TextInput, SwitchInput, Toolbar, Tooltip, …) now use the host semantic tokens and automatically adapt to whichever theme the user has selected. Built-in icons render with fill="currentColor".

A new set of CSS custom properties is available inside <Canvas>. See the full token reference for the complete list, including surface, ink, border, per-context variants, signal tones, and more.

`ctx.theme` is now deprecated

ctx.theme is still present and unchanged in shape, but the host now pins it to light-mode values only, regardless of the active theme. Existing plugins that read it keep rendering as before. Migrate to ctx.cssDesignTokens to follow the user's active theme.

Deprecated CSS variables (react-ui)

Two legacy groups remain for backward compatibility but will be removed in a future major version:

Structural legacy vars (--border-color, --base-body-color, --light-bg-color, --alert-color, …) — now resolve to the closest semantic token, so they already follow dark mode.
Theme-derived legacy vars (--accent-color, --primary-color, --light-color, --dark-color, …) — emitted from the deprecated ctx.theme, pinned to light-mode values. Mixing these with --color--* tokens in dark mode will produce mismatched colors.

Non-color tokens (--spacing-*, --font-size-*, --font-weight-bold, --material-ease, font families) are stable.

Upgrading

Test your plugin in dark mode before publishing. Common things to audit:

Hardcoded colors in your CSS (e.g. color: #333, background: white) — won't follow the theme.
Hardcoded SVG fills in custom icons — use fill="currentColor".
Custom CSS that mixes library components with your own colors — verify combinations in both themes.

See the dark-mode upgrade guide for full details.