Design & internals
This site documents using Transtyle. The project’s engineering documentation — written before the first line of code, and maintained since — lives in the repository and goes deeper on every topic here.
The design-first history
Transtyle was fully specified on paper before implementation: architecture, IR, plugin contracts, versioning policy, and eight initial decision records. The specification was then validated by a “paper compilation” exercise (hand-translating a design system to shadcn), which found three IR flaws before they became code — and the walking skeleton has been kept consistent with the specs since, each finding flowing back as a spec amendment.
Repository map
| Path | Contents |
|---|---|
docs/architecture/ |
The compiler pipeline, IR specification (DTCG superset, tiers, catalog, modes), derivation engine, plugin system, versioning & compatibility model |
docs/specs/ |
Configuration, CLI, validation & coverage, doc generation, the v2 component layer, and per-exporter specs (Bootstrap, shadcn, ECharts, Storybook) |
docs/adr/ |
Decision records — each with context, the decision, and the costs accepted |
docs/exercises/ |
The Phase 0 paper-compilation reports |
docs/prior-art.md |
Honest competitive analysis: Style Dictionary, Terrazzo, Tokens Studio, Supernova, and the Diez post-mortem |
packages/ |
ir, core, exporter-shadcn, cli — zero-dependency ESM |
examples/ |
Acme and Cathode, both compilable |
The decision records, in one line each
- ADR-0001 — compiler with a central IR, not an exporter collection: N importers + M exporters = N×M paths for N+M cost.
- ADR-0002 — DTCG superset, not a proprietary format: interop is table stakes; extensions must be deletable when the spec catches up.
- ADR-0003 — foundations first; the component layer waits for evidence (and is component theming, never component generation).
- ADR-0004 — plugins are npm packages with static, reviewable manifests.
- ADR-0005 — derivation is deterministic, rule-based, explainable; no ML, no silent invention.
- ADR-0006 — target versions are compatibility ranges with mapping profiles, not per-patch promises.
- ADR-0007 — our own preview site first; rebuilding upstream framework docs is permanently experimental.
- ADR-0008 — importers are first-class frontends that emit reviewable source files, never IR internals.
- ADR-0009 — token sources stay pure DTCG; modes and bindings may live in separate layers.
Contributing
The repo’s CONTRIBUTING.md states the sync rule this project lives by: a feature isn’t done until the README, the specs, this website, and the examples all agree with the code. Documentation drift is treated as a build failure of the project itself.