> ## Documentation Index
> Fetch the complete documentation index at: https://invoca-5bd45748-mintlify-6c3474a6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Token workflow

> Divergences, open decisions, and undocumented gaps for Token workflow.

See [Token workflow](/invoca-design-system/contribute/token-workflow) for the decided part of this page.

## Known issues

| ID                                                                                | Kind          | What                                                      |
| --------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------- |
| [**TITAN-DIV-01**](/invoca-design-system/foundations/divergences#titan-div-01)    | Divergence    | Tier-3 tokens alias primitives, never semantics           |
| [**TITAN-DIV-05**](/invoca-design-system/foundations/divergences#titan-div-05)    | Divergence    | The SCSS token surface is frozen at 82 names              |
| [**TITAN-DIV-09**](/invoca-design-system/foundations/divergences#titan-div-09)    | Divergence    | The naming specification and shipped tokens have diverged |
| [**TITAN-GAP-02**](/invoca-design-system/foundations/open-decisions#titan-gap-02) | Open decision | 112 of 244 tokens record nothing about what they are for  |
| [**TITAN-GAP-20**](/invoca-design-system/foundations/open-decisions#titan-gap-20) | Open decision | No approval path is recorded for a token change           |

## Gaps in the current rules

* **No approval path is documented.** Who decides a token should exist, who reviews the
  value, and whether design sign-off is required before merge — none of it is recorded. The
  mechanism on this page is the technical path only.
* **No naming review step.** A new token can be named anything the author chooses; nothing
  checks it against the [naming grammar](/invoca-design-system/foundations/overview#the-naming-grammar).
* **No rule for when a value earns a token.** One use, three uses, any use — undecided.
* **No deprecation path**, so the workflow is add-only. See
  [Versioning & deprecation](/invoca-design-system/contribute/versioning-and-deprecation).

## Constraints Titan should enforce

These are real, currently-true rules. Nothing in code stops a builder from violating them today — each is a placeholder for a guardrail Titan hasn't built, not a decision still being made.

| ID               | Constraint                                                                        | Would be enforced by                                                                                                                            |
| ---------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **TITAN-TOK-01** | A token is authored in the DTCG source, never added directly to a generated file. | A CI check (mirroring the doc-emission `--check` gate) that regenerates output from source and diffs against committed files, failing on drift. |
| **TITAN-TOK-02** | A token's value is an alias, never an inline literal.                             | A token-lint script rejecting semantic/component-tier `$value`s that aren't `{...}` alias syntax.                                               |
| **TITAN-TOK-03** | Every new token ships with a `$description`.                                      | A JSON-schema/build-time validation requiring a non-empty `$description` per token.                                                             |
| **TITAN-TOK-04** | A new component token aliases the semantic tier, or states why it doesn't.        | A lint rule checking the alias path resolves to `semantic.*` unless an explicit exception field is present.                                     |
| **TITAN-TOK-05** | A missing value produces a token proposal, never a literal in component code.     | An ESLint/stylelint rule flagging raw color/spacing literals where a token exists.                                                              |