workday/canvas-kit/sana-canvas-kit-tokens

Canvas Kit Tokens

Which token to use, by role — not a single version's path list. For how to apply tokens (createStyles, createStencil, cs), see /sana-canvas-kit-styling.

REQUIRED SUB-SKILL: /sana-canvas-kit-version. Run it first. This skill's path tables and family names assume current generation (@workday/canvas-kit-react 16.x + @workday/canvas-tokens-web 4.4+, Sana Canvas). If the version skill reports an older install, do not apply the tables below as current truth — use MCP get-canvas-kit-tokens plus the matching upgrade guide instead.

When to apply

• Choosing a color, spacing, shape, size, or typography value
• Pairing a background/foreground/border combination and needing it to stay accessible
• Migrating @workday/canvas-kit-react/tokens or deprecated system.* paths
• Translating Figma variables into token paths
• Reviewing token usage after a codemod (/sana-canvas-kit-migration)

For full inventories and old→new mapping tables (current-generation only), see references.md. For deeper token docs, call MCP get-canvas-kit-tokens and start with docs://tokens/v4/v4.4-token-reference.

Core rules

1. Run `/sana-canvas-kit-version` first — these tables are current-generation only.
2. Default to `system.*` — semantic, themeable tokens for almost everything.
3. Match the CSS property to the spacing family — wrong family is a semantic error even when

the pixel value matches.

1. Pick color by role, then pair by role — don't pick a foreground/background combination by

eyeballing contrast; use the pairing rules below so contrast is guaranteed.

1. Never use internal namespaces in application code — see Off-limits.
2. Verify in installed `node_modules` — @deprecated JSDoc on token paths always wins over

static tables.

Namespaces

import {system} from '@workday/canvas-tokens-web';
import {createStyles} from '@workday/canvas-kit-styling';
const styles = createStyles({
  backgroundColor: system.color.surface.default,
  color: system.color.fg.default,
  padding: system.padding.md,
  gap: system.gap.sm,
});

Each token is a CSS variable name, not a raw value. createStyles wraps whole property values in var() automatically. In template literals, wrap manually: ` 1px solid var(${token}) `.

Off-limits

Do not use these in application code:

• system.legacy.*, base.legacy, base.sana, brand.legacy, component.legacy — internal

backward-compat namespace for Canvas Kit's own library source, not for app code

• system.sana.* — internal Sana theme implementation detail
• @workday/canvas-kit-react/tokens (canvas, colors, space, type, depth, borderRadius)

Canvas Kit uses .legacy internally so published components keep working for consumers on older token packages. Write plain system.* and let theme CSS resolve the value.

Color — pick by role

Five families, split by the role the color plays:

Modifier ladder

Within a family, intensity is short: default, strong, and stronger (on fg only). There is no soft/softer/softest ladder on surface.* — that belonged to removed bg.*.

Deprecated color families

Only bg.default and bg.alt.default survive; prefer surface.default / surface.alt.default.

Accessible color pairings

Contrast is baked into the semantic token pairs below — pick a pairing, don't compose colors freely. WCAG 2.1 AA requires 4.5:1 for text ≤ 18pt (3:1 for larger/bold text), 3:1 for non-text UI (icons, control borders, focus rings).

Semantic pairs (default — always guaranteed)

Rules

• Match `fg` intensity to its surface/background modifier. bg.default/surface.default use

fg.default, fg.muted.default, or the stronger foregrounds listed in the semantic-pair table; brand.surface.primary.* uses brand.fg.primary.*. Don't use a foreground from another family.

• `fg.inverse` is for solid accent/brand fills — except light brand accents such as

brand.accent.caution, which use fg.contrast instead.

• Don't put accent fills on alt surfaces — never accent.* on surface.alt/bg.alt, even if

a contrast calculator says it passes. This is a design-system rule, not just a math check.

• Don't mix overlay families — surface.overlay.* is for neutral surfaces; accent.overlay.*

is for accent surfaces. Don't cross them.

• Don't stack translucent `surface.*` fills — many surface.* tokens use alpha values; nesting

them compounds the wash and can silently drop contrast below the guaranteed ratio.

• Never use color alone to convey state (error, required, success). Pair with an icon and text,

not color alone — see /sana-canvas-kit-accessibility for the full accessible-names guidance.

Escape hatch: composing from base when no semantic pair fits

If you're forced off system.* colors entirely (rare — usually only for data-visualization palettes), use the step-difference framework instead of eyeballing hex values:

The base palette is a 0 (lightest) → 1000 (darkest) tonal scale per color family. Compare step numbers between foreground and background; the difference must meet the table above. Do not invent or estimate a contrast ratio from a hex value — use the step framework or a calculator, and prefer a system.* semantic pair whenever one exists.

MCP: get-canvas-kit-tokens → docs://tokens/color-contrast. Full WCAG scenario guidance (forms, focus indicators, status messaging) lives in /sana-canvas-kit-accessibility — this skill only covers which tokens to pair.

Spacing — three families

system.space.x1–x20 are deprecated. There is no system.space in new code.

Quick reference