Reading the design tokens

The manual's design tokens as one document in the W3C design tokens format: colors, type, spacing, motion, radii, shadows and themes, each with a value and a type. The same document the export page offers as a file, so a build can fetch it instead of somebody downloading it after every change.

Request

GET https://stylehub.cloud/api/v1/manuals/{slug}/tokens.json

The slug and the headers are the same as for the manual. See Reading a manual.

Example

curl -sS https://stylehub.cloud/api/v1/manuals/acme/tokens.json -o tokens.json

The document

{
  "color": {
    "forest": { "$value": "#0f5132", "$type": "color" },
    "forest-500": { "$value": "#2f8a5a", "$type": "color" }
  },
  "dimension": {
    "8": { "$value": "8px", "$type": "dimension" },
    "breakpoint-md": { "$value": "768px", "$type": "dimension" }
  },
  "fontFamily": { "body": { "$value": "Inter", "$type": "fontFamily" } },
  "fontSize": { "md": { "$value": "16px", "$type": "dimension" } },
  "duration": { "fast": { "$value": "150ms", "$type": "duration" } },
  "cubicBezier": { "standard": { "$value": "cubic-bezier(0.2, 0, 0, 1)", "$type": "cubicBezier" } },
  "radius": { "card": { "$value": "12px", "$type": "dimension" } },
  "shadow": { "raised": { "$value": "0 2px 8px rgba(0,0,0,0.12)", "$type": "shadow" } },
  "theme": {
    "dark": { "background": { "$value": "#111111", "$type": "color" } }
  }
}

Every token is an object with $value and $type, grouped by kind. A group that has nothing in it is present and empty, so a build can rely on the keys being there.

The groups

Which block of the manual fills which group is in Design tokens, in thirteen formats. Only the W3C format is served here; the other twelve are files from the export page.

Using it in a build

The usual shape: fetch the document in the build step, write it next to the source, and let the tool that reads it, Style Dictionary or a script of your own, turn it into whatever the platform wants.

• Send the ETag back as If-None-Match. Most builds run far more often than the manual changes, and an unchanged manual is a 304 with no body. See Caching.
• Read the token from the environment of the build, never from a file in the repository.
• Token names are the names in the manual, lower cased and hyphenated. Renaming a color in the manual renames the token.

In a browser

A public or unlisted manual's tokens can be fetched from a page directly, no proxy needed. This paints the colors onto the document as CSS variables.

const res = await fetch("https://stylehub.cloud/api/v1/manuals/acme/tokens.json");
const tokens = await res.json();

for (const [name, token] of Object.entries(tokens.color ?? {})) {
  document.documentElement.style.setProperty("--brand-" + name, token.$value);
}