Skip to content

Tokens for designers

The TaishoDS Core token vocabulary explained for design, and how to bring the tokens into Figma. This page is the shared contract between the code and the design file.

How to read a shade

Each color family has 10 shades, from 100 (lightest) to 1000 (darkest) in light mode. They aren’t picked by hand. The engine generates them in OKLCH from a single hex seed and calculates the mirrored ramp for dark mode.

Shade What it’s for
500The family’s base color. It’s the one that represents the brand.
100 / 200Soft backgrounds and borders (chips, subtle status).
700Text on light surfaces. --ts-color-subtle uses gray-700 precisely because it meets AA.
Don’t invent in-between values or apply opacity to “lighten” a color. It breaks the calculated contrast. If a step is missing from the ramp, that’s a conversation about the seed.

The -contrast contract

Each chromatic shade comes with a -contrast twin, the text/icon color the engine guarantees is readable on that shade. You don’t have to pick it—it’s already worked out and checked against WCAG AA in the tests.

css
/* Brand background + its guaranteed text */
background: var(--color-brand-500);
color: var(--color-brand-500-contrast);
Families Has -contrast?
brand, brand-secondary, accentYes—all 10 shades
success, warning, info, dangerYes—all 10 shades
gray, grayAlpha, background, overlayNo (they’re surfaces, not brand backgrounds)

Status colors and density

The four status colors (success, warning, info, and danger) aren’t a single color. Each one comes with a set of sub-tokens ready to build a complete piece.

css
--ts-color-danger           /* the base color (shade 500) */
--ts-color-danger-bg        /* soft background (shade 100) */
--ts-color-danger-border    /* border (shade 200) */
--ts-color-danger-text      /* text on a light background (shade 700) */
--ts-color-danger-contrast  /* text on the base color */

Density: control heights and padding come in two sets—comfortable (default) and compact. They switch all at once, at runtime, without rebuilding. When you design, lay out the screen in comfortable and check that it still breathes in compact.


Bring the tokens into Figma

The engine exports the tokens in DTCG format (the Design Tokens Community Group standard), generated from the same source as the CSS, so there’s no parallel list that can drift out of sync. Here’s how they map to Figma:

In the JSON (DTCG) In Figma
Root group (color, sizing, spacing…)Variable collection
$valueLight mode value
$extensions["com.taishods"].darkDark mode value
$extensions["com.taishods"].hexColor Variable value (Figma doesn’t read OKLCH)
Alias {color.gray.1000}Alias to another Variable
$type: dimension { value, unit }FLOAT Variable (px)
$type: shadowEffect style (Figma doesn’t support shadow Variables)
Colors are stored in OKLCH, which Figma doesn’t read. That’s why each color carries an equivalent hex in $extensions, and that’s the one to import. OKLCH stays the source of truth for the code.

Tokens for the taisho theme (the one these docs use).