Tokens

The tokens command exports the 17 resolved semantic color tokens as structured data. It runs the same palette generation and template resolution pipeline as generate but outputs the token values instead of rendering target artifacts. This is useful for feeding colors into scripts, custom tooling, or formats that Chromasync does not have a target for.

Usage

chromasync tokens --seed "#4ecdc4" --template minimal

The command prints the resolved tokens to stdout and exits. No files are written.

Options

The --template flag accepts the same values as in generate — a built-in name, a user-config name, or a file path.

Output format

The default (and currently only) format is JSON. The output is a flat object with all 17 token names as keys and #RRGGBB hex strings as values:

{
  "bg": "#040303",
  "bg_secondary": "#090706",
  "surface": "#0E0A0A",
  "surface_elevated": "#1B1413",
  "text": "#F0E9E9",
  "text_muted": "#C4B3AF",
  "border": "#342521",
  "border_strong": "#533C36",
  "accent": "#E86C6C",
  "accent_hover": "#FA827F",
  "accent_active": "#CF5051",
  "accent_fg": "#010100",
  "selection": "#511718",
  "link": "#78AFEE",
  "success": "#8BAC55",
  "warning": "#D1A33C",
  "error": "#EC817A"
}

The JSON is pretty-printed with indentation. Token names use snake_case.

Semantic tokens

Every template resolves all 17 tokens. They are grouped by role:

Backgrounds and surfaces

Text

Borders

Accent

Selection and links

Status

Resolution pipeline

The tokens command runs the same pipeline as generate and preview:

1. Palette generation — the seed color is converted to OKLCH and used to derive 9 palette families (primary, secondary, tertiary, neutral, neutral_variant, error, success, warning, info), each with 16 tone samples spanning black to white.

2. Template loading — the template is loaded from built-in, user config, pack, or filesystem sources. Each template defines a rule for every token specifying which palette family and tone to sample, with optional chroma overrides.

3. Token resolution — for each of the 17 tokens, the resolver looks up the rule’s palette family, computes the final chroma as (chroma OR family.base_chroma) * chroma_scale, and converts the OKLCH triplet (family hue, final chroma, rule tone) to a #RRGGBB hex color.

4. Contrast adjustment — after all tokens are resolved, the resolver checks that text is readable against bg and that accent_fg is readable against accent. If a pair fails the contrast threshold, the resolver tries neutral light (tone=0.98) and dark (tone=0.06) fallbacks and picks the candidate with the best score. This ensures the exported tokens always meet accessibility requirements.

Contrast strategies

The --contrast flag selects the algorithm used in step 4:

The default relative-luminance is the widely adopted WCAG standard. The apca-experimental option uses a perceptually uniform model that better accounts for how the eye perceives contrast at different luminance levels. It is marked experimental and may change in future versions.

See Contrast strategies for more details.

Scripting with tokens

Because tokens outputs structured JSON, it integrates well with tools like jq:

Extract a single token

chromasync tokens --seed "#4ecdc4" --template minimal | jq -r '.accent'
# #4CBDB5

Build a shell color palette

eval "$(chromasync tokens --seed "#4ecdc4" --template minimal \
  | jq -r 'to_entries[] | "CHROMASYNC_\(.key | ascii_upcase)=\(.value)"')"

echo "$CHROMASYNC_ACCENT"
# #4CBDB5

Generate a custom config file

chromasync tokens --seed "#4ecdc4" --template minimal \
  | jq -r '"cursor_color=\(.accent)\nforeground=\(.text)\nbackground=\(.bg)"' \
  > ~/.config/myapp/colors.conf

Compare dark and light tokens

diff <(chromasync tokens --seed "#4ecdc4" --template minimal --mode dark) \
     <(chromasync tokens --seed "#4ecdc4" --template minimal --mode light)

Tokens vs preview

Both commands resolve the same tokens from the same pipeline. The difference is in output format and detail:

Use preview when you want to eyeball the colors. Use tokens when you need to feed them into another program.

Tokens vs generate

If you need output for a specific application, write a target instead of processing token JSON manually. Targets handle format-specific details like placeholder substitution and file naming.