systhema generate-references

Generate agent-facing TOON references at .systhema/references/tokens/. These references are consumed by the bundled skills (e.g. systhema:understanding-tokens) so that AI agents can read your project's design tokens efficiently.

systhema generate-references
systhema generate-references --dry-run    # log what would be written
systhema generate-references --verbose    # one line per file written

You rarely need to run this directly — both systhema sync and the project-local systhema-core sync generate references as their final step. The command proxies to the systhema-core generate-references subcommand; the generator itself lives in @systhemaui/core, so it works even without the global CLI installed.

Every run rewrites every file in the directory, so an upgrade picks up new values and new serialization with no extra step. The files are generated, never hand-edited: systhema doctor's stale-references check flags a tree an older @systhemaui/core wrote, and sync replaces it.

OptionsLink to this section

The reference formatLink to this section

The files are TOON (opens in new tab), a compact serialization aimed at LLM prompts. Each entry is a raw value, a ref and its already-resolved value, or a style token carrying the class it generates:

base:
  "0": "#FFFFFF"
  "900": "#171717"
foundations:
  bg: "#FFFFFF"
typography[3:]{ref,value}:
  label: "{foundations.text}","#000000"
  heading: "{foundations.text}","#000000"
  body: "{foundations.text}","#000000"

Two shapes are worth knowing, because both are the encoder's choice rather than anything about the data:

• A group whose entries all carry the same fields is written as a tabular block. The header names the entry count and the fields ([3:]{ref,value}), and each line is <key>: <field 1>,<field 2>. A group with one entry, or with entries that differ, keeps the indented form instead. The two are interchangeable.
• A #-leading string is quoted, because a line starting with # is a comment in TOON. That is why every hex value carries quotes; a # elsewhere in a value does not need them.

systhema:understanding-tokens teaches agents to read both forms.