Getting started

Transtyle is on npm as an alpha: @transtyle/cli. Node ≥ 22.12 is the only requirement. The compiler has zero external dependencies, so installing it brings nothing else with it.

1. Install#

npm i -D @transtyle/cli
npx transtyle --version

Pin the exact version while the project is in alpha: the token vocabulary, the generated output and the CLI surface can each change between alpha releases. Rather look before you install? The repository ships four complete design systems you can compile without authoring a token.

2. Scaffold your design system#

mkdir my-ds && cd my-ds
npx transtyle init

In a terminal, init asks five questions: your brand color, light and dark or light only, which targets, a preset and a file layout. Press Enter to take a default. Every question also has a flag (--brand '#e8590c' --targets shadcn,bootstrap), and without a terminal it asks nothing. The CLI reference lists them all.

The default recommended preset authors the minimum: six real decisions, each marked TODO with a description of what it is:

The five neutrals start as a near-gray ladder in your brand’s hue, each with a dark value: placeholders that already pass contrast, not your design. Only the brand color is required.

Leave the page background out and it defaults to white, or near-black in dark mode. Leave the body text out and it defaults to whichever of near-black and white contrasts more with the page. Author the body text without a dark value and leave the page out, and dark mode swaps the light pair: the page takes your text color and the text takes white. Both defaults are marked defaulted in report.json.

The five other decisions are what make the neutrals yours. Card background, muted text and the border derive from the page and the text too, but the scaffold asks for them because they’re part of your look. The minimal preset (--preset minimal) writes the brand color alone and leaves all of that to the defaults.

In DTCG form (this is the default scaffold’s tokens/brand.tokens.json, abridged):

{
  "$schema": "https://transtyle.dev/schemas/tokens/v0.json",
  "option": {
    "color": { "$type": "color", "brand": { "500": { "$value": "oklch(0.55 0.18 255)" } } }
  },
  "semantic": {
    "color": {
      "$type": "color",
      "primary": { "solid": { "$value": "{option.color.brand.500}" } },
      "elevation": {
        "0": { "surface": { "$value": "oklch(1 0 0)" } },
        "1": { "surface": { "$value": "oklch(0.985 0.003 255)" } }
      },
      "text": {
        "base": { "$value": "oklch(0.21 0.01 255)" },
        "muted": { "$value": "oklch(0.5 0.01 255)" }
      },
      "border": { "base": { "$value": "oklch(0.9 0.006 255)" } }
    }
  }
}

Note the two tiers. option.color.brand.500 is your name for your value, and primary.solid is the catalog slot that aliases it. The dark values sit in tokens/brand.dark.tokens.json, a mode-scoped DTCG file the config loads for color-scheme: dark only:

"tokens": [
  "tokens/brand.tokens.json",
  { "files": "tokens/brand.dark.tokens.json", "mode": { "color-scheme": "dark" } }
]

Values can also go inline per token (see Authoring tokens). Before it exits, init checks the new project and shows your brand color with the text color derived for it.

3. Add targets and build#

npx transtyle build             # starts with css-variables
npx transtyle add shadcn        # registers another target in the config
npx transtyle add bootstrap     # …any of the eleven official exporters
npx transtyle build

Each target gets a directory under dist/ holding its native artifacts, a generated usage.md telling you how to wire them into that ecosystem, and a report.json recording where every value came from.

Everything you didn’t author (hover states, on-colors, secondary, the full role grids, the chart palette) is derived deterministically. report.json says so per variable, so you can override selectively: author any slot and derivation yields to you.

Two more commands to know early:

npx transtyle check                    # same pipeline, no files written:
                                       # validation, alias cycles, WCAG contrast, coverage
npx transtyle explain primary.tint     # why does this value exist? full derivation chain

4. Use the theme in a real project#

For a Tailwind v4 shadcn app: copy globals.transtyle.css next to your global stylesheet and import it after Tailwind:

@import 'tailwindcss';
@import './globals.transtyle.css';

Dark mode uses the standard shadcn class strategy: toggle dark on <html>. The shadcn exporter page has the details for the Tailwind v3 era. Every target works the same way: build, then follow the generated usage.md. To see a theme on real components first, each example ships runnable demo projects per target.

5. Or start from the examples#

Nothing beats reading a design system that already compiles. The monorepo ships four, with runnable demos for every target:

git clone https://github.com/transtyle/transtyle
cd transtyle
npm install                  # zero external dependencies — this just links the workspaces
cd examples/acme
npx transtyle build shadcn

Output lands in dist/shadcn/:

• globals.transtyle.css: the complete shadcn theme (light + dark + @theme inline)
• usage.md: generated paste-in instructions for your target project
• report.json: coverage classification and provenance for every variable

Your first build walks through that output line by line.

Where next#

• Core concepts: the pipeline, tiers, the semantic catalog, modes, provenance
• The Transtyle language: every catalog slot, with derivation rules and per-exporter consumers
• Configuration: every manifest field
• Weird things & diagnostics: when output surprises you, it’s explained there