Overview

SDS design tokens are published as JSON using the W3C Design Tokens Community Group format, and as generated artifacts for common browser and JavaScript use cases.

The token JSON is the source of truth for generating platform-specific outputs such as CSS, Sass, React theme objects, Tailwind configuration, or design tool imports.

The generated files expose the same token set in ready-to-use formats.

CSS variables

Use tokens.css when a project needs SDS CSS custom properties but does not need the full SDS component styles.

<link rel="stylesheet" href="https://assets.soracom.io/sds/latest/tokens.css" />

Use CSS custom properties instead of hard-coded values when building or extending SDS components.

.custom-panel {
  padding: var(--ds-space-small);
  color: var(--color-default);
  font-family: var(--ds-font-default);
  font-size: var(--ds-text-size-medium);
  background-color: var(--color-background);
}

JavaScript tokens

Use tokens.mjs when consuming SDS tokens from JavaScript, React, chart configuration, or build tooling.

The module exports:

Use sdsTokens for browser-rendered UI so theme-aware tokens and dark mode continue to resolve through CSS.

import { sdsTokens } from "https://assets.soracom.io/sds/latest/tokens.mjs";

export function Panel({ children }: { children: React.ReactNode }) {
  return (
    <section
      style={{
        padding: sdsTokens.space.small,
        color: sdsTokens.color.default,
        fontSize: sdsTokens.textSize.medium,
        backgroundColor: sdsTokens.color.background,
      }}
    >
      {children}
    </section>
  );
}

Use sdsTokenValues when a build tool needs final values instead of CSS variable references.

import { sdsTokenValues } from "https://assets.soracom.io/sds/latest/tokens.mjs";

export default {
  theme: {
    extend: {
      spacing: {
        small: sdsTokenValues.space.small,
      },
    },
  },
};

Source JSON

Use the published tokens.json directly when generating output for another system. Each token entry includes a DTCG token path, $type, $value, and SDS extension metadata.

{
  "space": {
    "$type": "dimension",
    "small": {
      "$value": "20px",
      "$extensions": {
        "com.soracom.sds": {
          "cssVariable": "--ds-space-small"
        }
      }
    }
  }
}

For this token:

const response = await fetch("https://assets.soracom.io/sds/latest/tokens.json");
const tokens = await response.json();

const token = tokens.space.small;

console.log(token.$value); // "20px"
console.log(token.$extensions["com.soracom.sds"].cssVariable); // "--ds-space-small"

Token values may be literal values, CSS expressions, or references to other tokens using DTCG reference syntax such as {color.red} or {text-size.2xsmall}. Resolve references in your token pipeline before emitting formats that require final values.

Use the SDS extension metadata when generating named outputs:

Color tokens

Color tokens are available as CSS variables with the --color-* prefix.

Palette families

The available color families are:

Each family has fixed numbered tokens and theme-aware named tokens.

Fixed numbered tokens keep the same value in light and dark themes. Theme-aware named tokens use light-dark() and automatically map to an appropriate light or dark value.

Semantic color tokens

Use semantic color tokens when the color has a known purpose.

For visual swatches and accessibility guidance, see Colors.

Space tokens

Use space tokens for gaps, padding, margins, and layout rhythm.

Small-screen values apply at max-width: 599px.

Text size tokens

Text size tokens define the available SDS text sizes.

Icon size tokens

Icon size tokens define the available SDS icon sizes.

Font tokens

Font tokens are available for font families and font weights.

Opacity tokens

Opacity tokens are used by SDS to mix colors and represent common opacity levels.