Skip to content

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

Choose a tag to compare

View all tags
@stefanoverna stefanoverna released this 03 Jun 16:24
· 40 commits to master since this release
v2.2.1
93e5259

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.

Patch notes (v2.2.1)

  • Updated LICENSE.md in datocms-plugin-sdk
Assets 2
Loading