# 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.