Design Tokens | Gakaso for AI Agents | Docspi | docspi
Design Tokens
Published July 22, 2026
# Design Tokens
Gakaso manages design tokens (color, typography, spacing, shadow, radius, and similar values) per project, with import/export interoperable with the **W3C Design Tokens Community Group (DTCG)** format.
## Structure
Each token, as created via `gakaso_create_token` / `gakaso_import_tokens`, has:
- A **`category`**: one of `colors`, `spacing`, `typography`, `shadows`, `borders`, `other`. This is the actual categorization mechanism — there is no separate primitive/semantic/component "tier" concept in the current schema; category is the only grouping dimension a token carries.
- A **`name`** (string, ≤100 chars) and a **`value`** (string, ≤500 chars) — values are stored as plain strings (e.g. `"#3B82F6"`, `"16px"`), not as a nested DTCG `$value` object internally; DTCG shape is produced/consumed at the import/export boundary (see below), not as the storage format.
- An optional **`cssVar`** (auto-generated from the name if omitted).
- **Aliasing** is expressed *inline in `value`*, DTCG-reference-syntax style: a value like `"{color.brand.500}"` (curly braces around another token's `path` or `name`) is treated as a reference rather than a literal, and is followed at read time — there's no separate boolean/field marking a token as an alias. `gakaso_resolve_token_alias` follows a `{...}`-reference chain (up to 10 hops, with circular-reference detection) down to its final literal value.
## What you can do with tokens via MCP
| Action | Tool | Notes |
|---|---|---|
| Create / update / delete a token | `gakaso_create_token`, `gakaso_update_token`, `gakaso_delete_token` | `create`/`update` take `{ category, name, value, cssVar? }`. |
| List a project's tokens | `gakaso_list_tokens` | Optionally filtered by `category`. |
| Import tokens | `gakaso_import_tokens` | Either an array of `{ category, name, value, cssVar? }` (1–500 tokens), or a `w3cTokens` W3C-DTCG-format JSON **string** (W3C `$type` values are mapped onto Gakaso's category enum, e.g. `color`→`colors`, `dimension`→`spacing`, `fontFamily`/`fontWeight`→`typography`). `strategy`: `"merge"` (default — upsert by category+name) or `"replace"` (delete all existing project tokens first). |
| Export tokens | `gakaso_export_tokens` | `format`: `"json"` (default) / `"css"` / `"scss"` / `"w3c"` (W3C DTCG-shaped output, generated from the flat category/name/value storage at export time); optional `category` filter. |
| Distribute tokens across projects (multi-project / hub scenarios) | `gakaso_distribute_tokens` | Pushes a source project's tokens into one or more target projects — see `/team/management.md`'s note on project groups for the organizational layer this is typically used alongside. |
| Resolve an alias reference to its underlying value | `gakaso_resolve_token_alias` | Takes `tokenPathOrName`; returns the full resolution `chain` plus `resolvedValue` and `depth`. |
| Propagate a token change through dependent aliases/components | `gakaso_propagate_token_change` | Use after updating a heavily-referenced token (e.g. a brand color) so dependents pick up the new value rather than needing individual edits. |
| Analyze where/how a token is used | `gakaso_analyze_token_usage` | Useful before deleting/renaming a token, to check what would break. |
Token tools sit behind the standard read/write RBAC permission on the calling identity (see `/mcp/overview.md`) — a pair of token-scoped capability strings exist in the scope type system but, like most non-`frame:*` scopes, aren't currently enforced as a separate gate on these specific tools.
## Why this matters for generation
If you're authoring new UI (see `/canvas/application-mode.md`) or reading back a faithfully-imported UI (see `/mcp/faithful-roundtrip.md`), styling should reference project tokens (by `cssVar` or by DTCG-style `{path}` alias, per the project's convention) rather than hard-coded values wherever the project already has a relevant token — this is what keeps generated output visually consistent with the rest of the project and lets a human change the brand palette in one place later. A project's `tokenStrategy` section in its Product Design Capsule (see `/design/product-design-capsule.md`), if one has been set, records which tokens matter most for that product — check it before inventing new ad-hoc values. The `gakaso://manuals/design-principles` MCP resource (see `/design/diagram-intelligence.md`) also explicitly maps its design principles onto this token model, so consult it if you're generating new visual output rather than editing an existing token set.