Jetons (jetons v0.2.0)

A simple, flexible library for managing design tokens in Elixir.

Jetons generates compile-time token accessor functions from parsed JSON maps, with support for single or multiple themes (light/dark/custom).

Generated Functions

Single theme modules generate:

token/1 - Get token by path (returns nil if not found)
token!/1 - Get token by path (raises if not found)
list_<category>/0 - List all tokens in a category
group_by_path/2 - Group tokens by path depth
get_groups/1 - Get top-level groups for a category
get_in_group/2 - Get all tokens in a specific group

Multi-theme modules additionally generate:

token/2 - Get token by path for specific theme
token!/2 - Get token by path for specific theme (raises if not found)
list_<category>/1 - List tokens in category for specific theme
list/0 - List all tokens (uses default theme)
list/1 - List all tokens for specific theme
themes/0 - List all available theme names

Extending Jetons

Jetons supports custom transformers for generating output in any format. See the "Extending Jetons" guide for creating iOS, Android, or custom transformers.

What `use Jetons` Injects

When you use Jetons, it generates the following functions in your module:

Single Theme Mode:

token/1 - Retrieves token value by path (returns nil if not found)
token!/1 - Retrieves token value by path (raises KeyError if not found)
list_<category>/0 - One function per category (e.g., list_colors/0)
group_by_path/2 - Groups tokens by path depth
get_groups/1 - Returns sorted list of top-level groups
get_in_group/2 - Returns all tokens in a specific group

Multi-Theme Mode (when 2+ themes provided): All of the above, plus:

token/2 - Retrieves token with explicit theme parameter
token!/2 - Retrieves token with theme (raises if not found)
list_<category>/1 - List category tokens for specific theme
themes/0 - Returns list of all available theme names
All helper functions with /3 variants accepting theme parameter

Compile-Time Dependencies: Note that token files must exist at compile time. Changing token files requires recompiling any modules that use them.

Summary

Functions

__using__(opts)

Generates token accessor functions at compile time.

deep_merge(left, right)

See Jetons.Map.deep_merge/2.

extract_categories(tokens)

See Jetons.Parser.extract_categories/1.

extract_deprecated(config)

See Jetons.DTCG.deprecated/1.

extract_descriptions(config)

See Jetons.DTCG.descriptions/1.

extract_type_map(config)

See Jetons.DTCG.type_map/1.

flatten_tokens(map, prefix)

See Jetons.DTCG.flatten/2.

from_config(config)

See Jetons.Parser.from_config/1.

from_config(config, opts)

See Jetons.Parser.from_config/2.

from_files(groups)

See Jetons.Parser.from_files/1.

from_files(groups, opts)

See Jetons.Parser.from_files/2.

get_groups(tokens, category)

See Jetons.Query.get_groups/2.

get_in_group(tokens, category, group)

See Jetons.Query.get_in_group/3.

group_by_path(tokens, category, depth)

See Jetons.Query.group_by_path/3.

list_permutations(document)

See Jetons.Resolver.list_permutations/1.

parse_tokens(input)

See Jetons.Parser.parse_tokens/1.

resolve!(document, input \\ %{}, opts \\ [])

See Jetons.Resolver.resolve!/3.

resolve_extends(config)

See Jetons.DTCG.apply_extends/1.

resolve_file!(path, input \\ %{})

See Jetons.Resolver.resolve_file!/2.

resolve_token_refs(tokens)

See Jetons.Ref.expand/1.

Functions

using(opts)

(macro)

Generates token accessor functions at compile time.

Single Theme (No Theme Switching)

For single-theme tokens, provide one theme key:

defmodule MyTokens do
  use Jetons,
    main: File.read!("tokens.json") |> Jason.decode!()
end

MyTokens.token("color.text.primary")  # No theme parameter needed
MyTokens.list_color()                  # List all color tokens

Multiple Themes (With Theme Switching)

For multi-theme support, provide multiple theme keys:

defmodule MyTokens do
  use Jetons,
    light: File.read!("tokens/light.json") |> Jason.decode!(),
    dark: File.read!("tokens/dark.json") |> Jason.decode!(),
    high_contrast: File.read!("tokens/high-contrast.json") |> Jason.decode!()
end

MyTokens.token("color.text.primary")                # Uses default (first theme: :light)
MyTokens.token("color.text.primary", :dark)         # Explicit dark theme
MyTokens.token("color.text.primary", :high_contrast) # High contrast theme
MyTokens.themes()                                    # [:light, :dark, :high_contrast]
MyTokens.list_color(:dark)                           # List colors for dark theme