# TokoMo (@ds-mo/tokens)

> Design tokens for the ds-mo design system, shipped as CSS custom properties, JSON, and TypeScript constants. Light and dark themes switch through the `data-theme` attribute on the document root (`<html>`); container themes are not supported. Token names never change between themes. Choose tokens by meaning and rendering context, never by their current value.

Version: 9.1.0

## Start here

- [Token selection contract](agent.json): the authoritative, validated guidance. Principles, the nine color intents, every token family with useWhen/avoidWhen/constraints, and composition recipes, all using exact CSS variable names. Also shipped as `@ds-mo/tokens/agent`.
- [Token index](tokens-index.json): every token name and value, grouped by category. Use it to confirm a token exists. Also shipped as `@ds-mo/tokens/json/index`.

## Principles

- Choose by meaning and context: use documented semantic intents for system meanings, literal color-intent tokens when the hue itself is the intended user- or product-defined identity, and never choose reference-palette tokens directly.
- Treat backgrounds, foregrounds, borders, interactions, typography primitives, and elevation layers as related recipes rather than isolated visual values.
- Choose a token from the surface or product context where it will render; never choose by its current light-theme value.
- Use the same semantic token names in light and dark modes. Switch their mode-aware values with data-theme on the document root (<html>); container attributes do not switch token values, and nested token themes are not supported.
- When a distinction carries status, severity, selection, or other meaning, provide a non-color cue as well.

## Optional

- [Color generation](guidelines/color-generation.md): how the reference palette is built and audited. For maintainers of TokoMo only.