Skip to content
xtyle

Getting Started

Install the CLI

Section titled “Install the CLI”
Terminal window
npm install -g @xtylejs/cli

The xtyle CLI provides three commands: compile, validate, and resolve.

1. Create a Definition

Section titled “1. Create a Definition”

Create a file called brand.xtyle.json:

{
  "xtyle": "1.0",
  "name": "my-brand",
  "visual": {
    "palette": {
      "ocean": "#0077B6",
      "sand": "#F4E8C1",
      "ink": "#1D1D2C"
    },
    "semantic": {
      "primary": "ocean",
      "surface": "sand",
      "text": "ink"
    },
    "typography": {
      "families": {
        "heading": ["Georgia", "serif"],
        "body": ["system-ui", "sans-serif"]
      },
      "scale": { "base": "16px", "ratio": 1.25 }
    }
  },
  "verbal": {
    "identity": {
      "name": "My Brand",
      "tagline": "Something worth saying."
    }
  }
}

Only xtyle and name are required. Everything else is optional — add what you need.

YAML is also supported. The same definition as brand.xtyle.yaml:

xtyle: "1.0"
name: my-brand
visual:
  palette:
    ocean: "#0077B6"
    sand: "#F4E8C1"
    ink: "#1D1D2C"
  semantic:
    primary: ocean
    surface: sand
    text: ink
  typography:
    families:
      heading: [Georgia, serif]
      body: [system-ui, sans-serif]
    scale:
      base: 16px
      ratio: 1.25
verbal:
  identity:
    name: My Brand
    tagline: Something worth saying.

2. Validate It

Section titled “2. Validate It”
Terminal window
xtyle validate brand.xtyle.json

3. Compile

Section titled “3. Compile”

Compile to one or more targets with a single command:

Terminal window
xtyle compile brand.xtyle.json --target css
xtyle compile brand.xtyle.json --target llm-prompt
xtyle compile brand.xtyle.json --target svelte
xtyle compile brand.xtyle.json --target css llm-prompt svelte

Output goes to ./out/ by default. Override with --outdir:

Terminal window
xtyle compile brand.xtyle.json --target css --outdir ./build

CSS output

Section titled “CSS output”

The CSS target produces custom properties and component classes:

:root {
  --xtyle-palette-ocean: #0077B6;
  --xtyle-palette-sand: #F4E8C1;
  --xtyle-palette-ink: #1D1D2C;
  --xtyle-color-primary: #0077B6;
  --xtyle-color-surface: #F4E8C1;
  --xtyle-color-text: #1D1D2C;
  --xtyle-font-heading: Georgia, serif;
  --xtyle-font-body: system-ui, sans-serif;
  --xtyle-font-size-base: 16px;
  --xtyle-font-scale-ratio: 1.25;
}

LLM Prompt output

Section titled “LLM Prompt output”

The LLM Prompt target produces a Markdown file structured as a system prompt for AI content generation.

Svelte output

Section titled “Svelte output”

The Svelte target generates Svelte 5 components from any visual.components definitions.

4. Resolve a Cascade

Section titled “4. Resolve a Cascade”

If your definition has a parent field, use resolve to see the fully merged result:

Terminal window
xtyle resolve child-brand.xtyle.json

This walks the parent chain, deep-merges all definitions (child wins), and prints the resolved JSON to stdout.

5. Use It

Section titled “5. Use It”

Link the CSS file and use the custom properties in your styles:

body {
  font-family: var(--xtyle-font-body);
  background: var(--xtyle-color-surface);
  color: var(--xtyle-color-text);
}


h1 {
  font-family: var(--xtyle-font-heading);
  color: var(--xtyle-color-primary);
}

Next Steps

Section titled “Next Steps”