Docs

This page isn't translated yet

next

Generated artifacts

What sync writes to .systhema/artifacts, the generated TypeScript types and the TOON references for agents.

On this page

systhema-core sync turns your tokens and config into generated files under .systhema/: copies of the tokens, TypeScript types, a class safelist and summaries for coding agents. The Tailwind plugin, the components and your editor read these files. This page lists each one, says what reads it, and when it is regenerated.

The .systhema folderLink to this section

.systhema/
├─ artifacts/
│  ├─ tokens/                  manifest.json and the token JSON files it lists
│  ├─ tokenMap.ts, tokenMap.js a module that imports every token file
│  ├─ types.ts, types.d.ts, types.js
│  ├─ safelist.txt
│  └─ .generator.json          the artifact format stamp
├─ references/
│  └─ tokens/                  _index.toon and one .toon file per collection and mode
├─ .meta.json                  what the last sync was generated from
└─ managed-files.json          hashes of the app files Systhema manages (Payload projects)

Everything except managed-files.json is generated and ignored by git: the templates' .gitignore excludes .systhema/* and keeps !.systhema/managed-files.json.

Token artifactsLink to this section

artifacts/tokens/ holds manifest.json and a copy of every token file the manifest lists, taken from the manifest your config points at. Without a configured manifest, sync copies the default tokens bundled with @systhemaui/core. tokenMap.ts and tokenMap.js import those files statically, so bundlers can follow them.

These are the values before customTokens is applied. customTokens is merged when the tokens are read, so to see an effective value, read the generated CSS variable rather than the JSON. See Verifying an override.

@systhemaui/core keeps its own copy of the artifacts inside the package (its dist/tmp folder), which is what the Tailwind plugin and getTokens() read. That copy is refreshed from .systhema/artifacts/ by sync, by the postinstall script (systhema-core refresh-cache), and when the Tailwind plugin starts. A reinstall resets the package copy to the defaults until one of those runs.

Generated typesLink to this section

artifacts/types.ts, types.d.ts and types.js hold the TypeScript types built from your tokens: ColorSystem (your themes), LayoutBackground, ButtonVariant, CardVariant, GapSize, AspectRatio and more. The common ones are re-exported from @systhemaui/core; the rest come from @systhemaui/core/tmp/types.

import type { ButtonVariant, ColorSystem } from '@systhemaui/core'

Rename a theme or a button variant in Figma, sync, and the type checker shows every place that still uses the old name. See Generated types.

SafelistLink to this section

artifacts/safelist.txt lists classes that Tailwind cannot find by scanning your source, so the plugin keeps them anyway: the classes built from token names (button-<variant>, card-<variant>, accordion-<variant>, bg-layout-<background>, color-<role>, column-span-<n>), the classes in packages.react.animationClasses and transitionClasses, and classes the packages emit from node_modules (Swiper, parallax, figure width and alignment, reveal control). The CSS optimizer's class obfuscation reads it too.

Agent referencesLink to this section

references/tokens/ holds TOON files: _index.toon (collections, themes, breakpoints, the generated text classes and the naming rules) and one file per collection and mode, such as colorSystem.dark.toon or responsiveSizing.lg.toon. TOON is a compact, readable format for language models; coding agents with the Systhema skills read these files to use your tokens instead of guessing. They are generated from the artifacts, so they show values before customTokens.

sync rewrites the whole folder every time, so a stale or hand-edited reference never lingers. systhema generate-references regenerates only the references. See systhema generate-references and Skills.

StampsLink to this section

  • artifacts/.generator.json records the artifact format. When a newer @systhemaui/core changes the format, the next sync replaces the old artifacts.
  • .meta.json records the core version, a hash of the manifest and a hash of the artifacts, so tools can tell when the artifacts are out of date.

When to run syncLink to this section

Run pnpm sync (the templates' script for systhema-core sync; a Payload project's script also regenerates the Payload types and import map) after:

  • cloning the project or deleting .systhema/,
  • a new token export from Figma, or a change to manifest, customTokens, spacing or locales in systhema.config.ts,
  • upgrading @systhemaui/* (systhema upgrade runs it for you).

Restart the dev server afterwards so the Tailwind plugin reads the new tokens. In a CI or Docker build, run pnpm sync before next build or copy .systhema/ into the build. Without artifacts the build uses the default tokens.

systhema doctor reports stale artifacts (stale-token-artifacts) and stale references (stale-references), and systhema doctor --fix runs the sync. systhema-core clean deletes .systhema/ and resets the package copy. See systhema-core and systhema doctor.

RelatedLink to this section