Status & roadmap
Transtyle’s design phase produced a complete blueprint before any code; the walking skeleton implements the core slice end-to-end. This page is the honest ledger of which is which.
Implemented today (v0.1 walking skeleton)
| Area | Status |
|---|---|
| Compiler pipeline (load → normalize → derive → resolve → emit → report) | ✅ end-to-end, byte-deterministic |
| DTCG-superset token loading, aliases, cycle detection, tiers | ✅ |
Modes: any number of independent dimensions (e.g. color-scheme + density), inline $extensions and mode-scoped layer files |
✅ equivalent by construction; single-dimension configs unaffected |
| Derivation: standard@1, the role grid (prominence × state per color role), the elevation ladder, content hierarchy, and full foundations scales (space/size/border-width/breakpoint/z/type/motion) + radius family aliases | ✅ with provenance |
| OKLCH color engine, WCAG 2.1 contrast checks | ✅ zero-dep, in-house |
| shadcn/ui exporter, tailwind-v4 + tailwind-v3 era profiles | ✅ |
| Apache ECharts exporter: per-mode theme JSON + self-registering scripts, 8-color derived palette | ✅ |
| daisyUI exporter (v5 era): light+dark theme blocks, brand-direct role mapping | ✅ |
Bootstrap exporter (≥5.3): Sass path (_variables + _maps) and CSS-variable path |
✅ engine-exact vs the Phase 0 fixtures |
| Storybook exporter (SB 8–9): chrome ThemeVars + sibling preview composition | ✅ |
css-variables exporter: the plugin-API reference implementation, full catalog as --custom-properties |
✅ 466 declarations (304 distinct) on Acme, 100% native |
| Radix Colors/Themes exporter: 12-step scales + alpha + contrast per role — the role grid’s own acceptance test | ✅ only 2 of 12 steps needed a fresh mix; surfaced (and fixed) a gamut-clamp gap in text-strong |
PrimeNG exporter: definePreset(Aura, overrides) — the first target with its own three-tier component-token system; one generic severity-grid mapper + exporter-private archetype helpers, proven on Button/Tag/Badge/Message/InlineMessage/Listbox/Menu/Popover/Dialog |
✅ first Angular demo in the repo; every preset type-checked against PrimeNG’s own DesignTokens types |
Role archetypes: custom semantic.color.<name> roles declaring $extensions.transtyle.role derive the full grid like a built-in and export to open-role targets (daisyUI, css-variables) |
✅ Cathode’s crt-amber as showcase |
Multi-dimension modes: a second independent mode dimension (e.g. density) alongside color-scheme; css-variables emits a [data-<dim>="<value>"] block per non-default value; targets that don’t express it report dropped(mode:<dim>) |
✅ Acme’s density: comfortable|compact (space.* × 0.875) as the worked example |
Per-example demo projects (examples/*/demo/*): the same fake app per target, npm-run-dev-able |
✅ consume dist/ only |
| Target instances (one exporter, many configs) | ✅ |
Coverage report (report.json) + diagnostics with stable codes |
✅ |
CLI: build, check, explain, init, add, diff, --cwd, check --json |
✅ golden-tested (check:cli) |
DTCG structural validation: unrecognized $type, missing $value, tier violations, foreign $extensions namespaces |
✅ new stable codes (docs/specs/validation-and-coverage.md), fixture-tested |
Component tier (component.control.*, component.button.*, component.tooltip.max-width, semantic.opacity.disabled), layered over the semantic tier |
✅ driving Bootstrap’s and PrimeNG’s component surfaces; every inventoried slot accounted for by check:coverage-bar |
Plugin conformance kit (@transtyle/plugin-kit): shape, determinism, IR immutability, coverage honesty, schema validity |
✅ gates all 8 official exporters + an inline third-party plugin in CI (check:plugins) |
Published JSON schemas for transtyle.config.json and report.json, validated at load time |
✅ one source of truth, regenerated by gen:schemas, enforced by check:schemas |
| Examples: Acme (minimal), Cathode (hostile), GOV.UK and Carbon (real, independently-designed) | ✅ |
Ground-truth checks: catalog completeness + frozen fixture values (check:grid), Phase 0 fixture diffing (check:fixtures), byte-for-byte determinism (check:determinism) — chained as check:all |
✅ |
| CI (GitHub Actions): every check above + site build + a matrix build of all 32 demo projects, on every push/PR | ✅ |
2026-07-20 — the catalog revision: the semantic catalog was rebuilt around the role grid — the finding, from a 14-ecosystem comparative study (docs/proposals/0001-universal-token-ir.md), that every mature design system samples the same prominence × state grid per color role. Landed as a pre-release breaking revision — Transtyle is unreleased, so old slot names were removed outright rather than aliased, and no version number moved (still IR spec v0; see docs/adr/0010-pre-release-breaking-changes.md). All five shipped exporters, both examples, and their fixtures were migrated in the same change (css-variables, added after, was built fresh against the new catalog); color values are unchanged except one documented, intentional refinement (overlay/popover is now a genuinely deeper elevation level, not an alias of the raised-card level). Sequenced in docs/plan/catalog-revision.md.
Specced, not yet implemented
Design-complete in the repo’s docs/ (architecture specs + ADRs), waiting their turn:
| Feature | Where the design lives |
|---|---|
CLI: import, preview, migrate; richer init (interactive) and explain (--target) |
docs/specs/cli.md |
Derivation overrides, user rule expressions, autoDark color synthesis (darkBrandAdjust — open research question, docs/exercises/phase0-shadcn.md F7) |
docs/architecture/derivation.md |
| Importers (Figma variables, Tailwind config, Bootstrap Sass) | ADR-0008 |
| Plugin packaging and a third-party exporter pilot (the conformance kit itself shipped — see above) | docs/architecture/plugins.md |
Lockfile (transtyle.lock), --frozen CI mode |
docs/architecture/versioning.md |
The rest of the component theming layer (v2) — the shared component.* tier itself shipped, on Bootstrap and PrimeNG |
docs/specs/component-layer.md, ADR-0003 |
Sequencing (from the project ROADMAP)
- Phase 0 — validate the IR (in progress): shadcn round done on paper (three IR amendments accepted); the ECharts round was validated directly in code — the exporter shipped without requiring IR changes; the Bootstrap round (the hardest constraint set) — zero IR-catalog changes, one rule-pack amendment (radius-scale derivation), round 1’s key amendment confirmed as general; the Storybook round (meta-target) — zero amendments, first clean attempt. The shadcn re-run then found a subtle-foreground rule ambiguity precisely because it diffed the paper expectation against real compiler output — the rule is now ratified in spec and code together, the clean-attempt counter reset, and the exercise protocol upgraded to require the output diff. Under the ratified rules, the next shadcn attempt came back clean on both probes. The Bootstrap re-run then diffed its hand maps against the derivation engine directly and found two more: a catalog slot that was guaranteed but underivable (
<role>.contrast), and unpinnedmixsemantics hiding a polar-vs-cartesian hue bug in border tints — both ratified in spec and code, shipped outputs unchanged, counter reset. Two machine-vs-hand diffs in a row caught what spec re-reading could not. The Bootstrap and shadcn re-runs under the ratified rules then both came back clean, with the verification mechanized — fixture values exact-matched against fresh engine runs. The Phase 0 exercise exit criterion is met (21 findings over 8 rounds; the ones that mattered most were only findable by diffing hand expectations against the machine). Remaining in Phase 0: the formal freeze declaration of IR spec v0 and plugin API v0, plus the naming tail. - Phase 1 — foundations compiler + four reference exporters, npm publication,
init. Eight exporters shipped rather than four; npm publication was deliberately parked until the first alpha, and that alpha is now being released (experimental, under thealphadist-tag). - Phase 2 — trust & workflow: preview site and importers beyond DTCG.
explain,diffand the plugin conformance kit landed early, in Phase 1. Exit criterion for v1.0: a third party ships a working exporter using only public docs. - Phase 3 — ecosystem translation: importers from Bootstrap/MUI/shadcn; round-trip fidelity reporting.
- Phase 4 — component theming layer (v2) — partially pulled forward by the first-alpha definition (2026-07-23): the shared
component.*catalog, generalized from two real component-heavy implementations (PrimeNG shipped; Bootstrap is the alpha’s second prototype), is now part of the first-alpha bar. The remainder of the layer stays Phase 4.
The first alpha — the first published, publicly deployed release — is defined in the project ROADMAP (2026-07-23): a large DTCG-speaking design system exports to rich component libraries (Bootstrap, PrimeNG) with all three tiers mapped — raw/option, semantic, and component tokens — proven on the Carbon and GOV.UK examples, plus a reference-docs rewrite and a diagnostics polish pass. Non-DTCG importers (Tailwind, Figma, CSS custom properties) are explicitly post-alpha.
What is deliberately never coming
No runtime shipped to your app. No component implementation generation. No visual editor. No AI inside the compiler (deterministic rules only — AI belongs outside, writing config; see AI agents). No pixel-perfect-equivalence claims — the coverage report exists precisely because translation is lossy.