@ds-mo/tokens
v6.5.0
Published
TokoMo design tokens — colors, dimensions, typography, and effects as CSS custom properties, JSON, and TypeScript constants
Maintainers
zainadeelReadme
@ds-mo/tokens
Design tokens as CSS custom properties, JSON, and TypeScript constants — the token foundation for the CompoMo design system.
Part of the design system trilogy:
TokoMo (@ds-mo/tokens) → IcoMo (@ds-mo/icons) → CompoMo (@ds-mo/ui)
Figma-first: tokens are exported from Figma variables and built into CSS via generator scripts. Drop in new JSON, run the build, everything updates.
Install
npm install @ds-mo/tokens
# or
pnpm add @ds-mo/tokens
# Local development (no npm publish needed):
pnpm add file:../path/to/tokomoUsage
CSS
/* All tokens at once */
@import '@ds-mo/tokens';
/* Or selectively */
@import '@ds-mo/tokens/colors';
@import '@ds-mo/tokens/dimensions';
@import '@ds-mo/tokens/typography';
@import '@ds-mo/tokens/effects';
/* Optional: base styles (font loading, reduced-motion, focus rings) */
@import '@ds-mo/tokens/globals';
/* Optional: CSS reset */
@import '@ds-mo/tokens/reset';JS / TypeScript (via bundler)
import '@ds-mo/tokens';
import '@ds-mo/tokens/globals';
// Type-safe token name constants
import { colorBackgroundPrimary, dimensionSpace200 } from '@ds-mo/tokens/ts';
// value is just the CSS variable name string: '--color-background-primary'
element.style.setProperty(colorBackgroundPrimary, 'red');JSON (for tooling, plugins, etc.)
import tokens from '@ds-mo/tokens/json';
import colors from '@ds-mo/tokens/json/colors';Selection guidance
@ds-mo/tokens/agent is the single machine-readable contract for choosing and composing tokens. It contains framework-neutral principles, the nine color intents, token-family guidance, and recipes for semantic color pairing, interaction layers, typography composites, and elevation.
import guidance from '@ds-mo/tokens/agent';
const colorFamilies = guidance.families.filter(family => family.category === 'color');
const typeRecipes = guidance.recipes.find(recipe => recipe.id === 'token-recipe:typography-composites');The documentation site renders the same contract for people under Browser / Documentation / Color Tool. The Browser shows values; Documentation intentionally explains selection with token names only.
Theming
Light/dark theme is controlled via a data-theme attribute on <html>:
document.documentElement.setAttribute('data-theme', 'dark');
document.documentElement.setAttribute('data-theme', 'light');Light is the default. No JS required — pure CSS variable overrides.
Token categories
| File | Prefix | Contains |
|---|---|---|
| colors.css | --color-* | Semantic colors (light + dark), reference palette, data viz |
| dimensions.css | --dimension-* | Space, radius, size, stroke-width, fixed layout constraints, transforms, and z-index |
| typography.css | --typography-* | Font family, weight, font-size, line-height, letter-spacing, paragraph spacing |
| effects.css | --effect-* | Blur, animation timing, easing, elevation shadows |
Typography ships CSS primitives rather than .text-* classes. TokoMo itself defines the recommended display/title/body/caption × regular/emphasis composites in @ds-mo/tokens/agent, so any framework or component library can implement them consistently. See docs/guidelines/typography-usage.md.
Scaling
--dimension-base is 8px. The spacing, radius, size, and stroke-width category bases alias it by default, so one override scales those four token scales together:
:root {
--dimension-base: 10px;
}Each category also has its own override point. Radius therefore has a separate base while still resolving to the same 8px default:
:root {
--dimension-space-base: 10px;
--dimension-radius-base: 6px;
}Fixed layout widths/heights, z-index layers, unitless transform scales, and --dimension-radius-half do not inherit --dimension-base; choose those by their documented role rather than expecting a global scale override. Offset tokens do follow the spacing base.
Elevation
Each suffix publishes a public outer shadow, inset highlight, and combined elevation token. Use the combined token by default:
/* Normal one-element case */
.surface { box-shadow: var(--effect-elevation-elevated-sm); }
/* Split only when the paint/clipping hierarchy requires two layers */
.surface-frame {
box-shadow: var(--effect-shadow-elevated-sm);
}
.surface-content {
overflow: hidden;
box-shadow: var(--effect-highlight-elevated-sm);
}Keep split parts on the same suffix. An element's own overflow does not automatically require a split; use it when an ancestor or inner clipping boundary would otherwise cut a descendant's outer shadow. See docs/guidelines/elevation-usage.md.
Available: elevated-none, elevated-sm, elevated-md, elevated-floating, depressed-sm, depressed-md, elevated-panel-top/right/bottom/left
Updating from Figma
- Export updated variable JSON from Figma
- Drop into
src/json/{colors,dimensions,typography,effects}/ - Run the build:
node scripts/build.mjsDev
node scripts/build.mjs # full build
node scripts/build.mjs --watch # watch modeLicense
MIT