Using Transtyle with AI agents

Transtyle is designed to be operated by AI agents as a first-class use case. The compiler contains no AI, on purpose (see below). Agents are good at driving a deterministic compiler with machine-readable contracts.

Why the design already fits agents#

The agent workflow#

A careful human uses the same loop, and a machine can run all of it:

# 0. Learn the vocabulary: every slot, its type, how it derives
npx transtyle catalog --json
# 1. Author or edit tokens (plain JSON, schema known)
# 2. Validate without side effects
npx transtyle check          # exit code + coded diagnostics on stderr
# 3. Build
npx transtyle build shadcn
# 4. Read the machine report
cat dist/shadcn/report.json  # coverage classes + provenance per variable
# 5. Iterate: author overrides for anything classified `derived` that
#    the human (or a screenshot evaluation) rejects

Concrete recipes:

• “Make me a theme from this brand color”: write an 11-token project like the Acme example, run build, return globals.transtyle.css. Derivation does the heavy lifting. The agent only supplies the brand facts.
• “Fix the contrast warnings”: run check and filter stderr for TST2101. Each one includes the measured contrast (a WCAG ratio, or an APCA Lc when check --json’s contrast.standard is apca), the token pair, and the mode. Adjust the named token’s lightness in OKLCH, re-run until clean.
• “What breaks if I change this token?”: run check --matrix --json and read matrix.slots["<slot>"]: the targets that read the slot, each with its coverage class and the variables it maps to. A target missing from that object never reads the slot, so editing it there is a no-op. After a build, the same per target is reads in its report.json. The slot matrix page is the same answer for the official exporters.
• “Why does this target variable have this value?”: run explain --variable '<name>' --target <t> --json. It returns the variable’s coverage rows, the variables it’s chained to, the slots it reaches (slots) and one provenance tree per slot (trees), down to what was authored. explain <slot> --target <t> --json answers the other way round, in target.consumers.
• “Which config is this product built from?”: read config in its report.json or in check --json: the files of the extends chain, base first, relative to the product. A shared value belongs in the base; after editing it, transtyle diff in each product shows what changed there.
• “What should I author next?”: run check --completeness complete --json and read completeness.todo: the slots that need a decision, in the order they pay off, each with its state (missing, derived, defaulted, carried-over) and a reason. Author the first few, re-run, stop when the list holds only what the human is happy to leave to derivation.
• “Did someone edit the generated files?”: run check --json and read the TST1312 diagnostics: each names a generated file whose content no longer matches the transtyle-manifest.json its last build wrote, or that is gone. Move the edit into the tokens or the config, then build.
• “Port this design system’s weird vocabulary”: follow the Cathode pattern: express the vocabulary as custom semantic tokens, then write one-line catalog bindings. The agent never needs to understand the whole system, only to map meanings. Each target’s report.json then says how many of those tokens reach it (coverage.customVocabulary) and lists the ones with no path as dropped rows named (custom:<path>): the bindings still missing for that target. Then run check --json and read adoption.unbound: the custom tokens no catalog slot reads yet, each with hints (the slots already set to the same value, or the slot whose name it shadows). Done when that list holds only the tokens meant for css-variables alone, and TST1124 (a secondary or accent bound with shadcn’s meaning) is absent. Start from bind --suggest --json: every unbound slot with its ranked candidates, each with a confidence and its reasons; review the contested and low ones first, they are the judgment calls.

Machine-readable documentation#

This site is agent-consumable by construction:

• /llms.txt: the llms.txt convention: a compact index of this documentation with one-line summaries.
• /llms-full.txt: the entire documentation concatenated as plain markdown, for context windows that can afford it.
• Every docs page as raw markdown: append .md to any docs URL (for example /docs/configuration.md) to get the source markdown instead of HTML. Each HTML page links its markdown twin.
• Stable heading anchors: slugs are generated deterministically from heading text; deep links don’t rot between builds.

The boundary: AI outside, determinism inside#

Transtyle will never embed AI in the compilation pipeline (the vision’s non-goal #5). Derivation is deterministic rules, because a brand pipeline that produces different output on different days is worthless, to companies and to agents, which need reproducibility more than humans do.

The intended division of labor: agents write config; the compiler compiles it. An agent with taste (or with a human in the loop) decides that info should be amber on a CRT theme; Transtyle guarantees that decision reaches every target, identically, forever. The deterministic core is what makes agent-driven theming auditable: every value in production traces to either an authored token (someone’s decision) or a versioned rule (everyone’s convention).