load

Documentation

Overview

Package load provides a high-level API for loading design tokens.

Index

• Constants
• Variables
• func Load(ctx context.Context, spec string, opts Options) (*token.Map, error)
• type Fetcher
• type HTTPFetcher
  • func NewHTTPFetcher(maxSize int64) *HTTPFetcher
  • func (f *HTTPFetcher) Fetch(ctx context.Context, url string) ([]byte, error)
• type Options

Constants

const (
	// DefaultTimeout is the maximum time to wait for a network fetch.
	DefaultTimeout = 30 * time.Second

	// DefaultMaxSize is the maximum allowed response size (10 MB).
	DefaultMaxSize int64 = 10 * 1024 * 1024
)

Variables

var (
	// ErrLocalResolution indicates that local filesystem resolution failed.
	ErrLocalResolution = errors.New("local resolution failed")

	// ErrNetworkFallback indicates that the CDN network fallback also failed.
	ErrNetworkFallback = errors.New("network fallback failed")
)

Functions

func Load

func Load(ctx context.Context, spec string, opts Options) (*token.Map, error)

Load loads design tokens from a specifier with full resolution.

The specifier can be:

• Local file path: "tokens.json" or "/path/to/tokens.json"
• npm package: "npm:@scope/pkg/tokens.json" (requires node_modules)
• jsr package: "jsr:@scope/pkg/tokens.json" (requires node_modules)

When Options.Fetcher is set, npm: and jsr: specifiers that fail local resolution will fall back to fetching from a CDN (configurable via Options.CDN).

The loading process:

1. Optionally loads config from .config/design-tokens.yaml
2. Applies Options values (they take precedence over config)
3. Resolves specifier to file content via filesystem (with optional CDN fallback)
4. Detects schema version (if not specified)
5. Parses tokens
6. Resolves $extends (v2025.10)
7. Resolves aliases
8. Returns *token.Map

Types

type Fetcher

type Fetcher interface {
	Fetch(ctx context.Context, url string) ([]byte, error)
}

Fetcher fetches content from a URL.

type HTTPFetcher

type HTTPFetcher struct {
	// contains filtered or unexported fields
}

HTTPFetcher fetches content over HTTP with size limiting.

func NewHTTPFetcher

func NewHTTPFetcher(maxSize int64) *HTTPFetcher

NewHTTPFetcher creates an HTTPFetcher with the given maximum response size.

func (*HTTPFetcher) Fetch

func (f *HTTPFetcher) Fetch(ctx context.Context, url string) ([]byte, error)

Fetch fetches content from the given URL.

type Options

type Options struct {
	// Root is the directory for local specifier resolution (required for local/npm: paths).
	Root string

	// FS is the filesystem to use. Defaults to OS filesystem if nil.
	FS fs.FileSystem

	// Prefix is the CSS variable prefix for tokens.
	// Takes precedence over config file if set.
	Prefix string

	// GroupMarkers are token names that can be both tokens and groups (draft only).
	// Takes precedence over config file if set.
	GroupMarkers []string

	// SchemaVersion overrides auto-detection from file content.
	// Takes precedence over config file if set.
	SchemaVersion schema.Version

	// Fetcher enables opt-in network fallback for package specifiers.
	// When set, if local resolution fails for an npm: or jsr: specifier,
	// Load will attempt to fetch the content from a CDN.
	// Nil means no network fallback (default).
	Fetcher Fetcher

	// CDN selects the CDN provider for network fallback.
	// Takes precedence over config file if set.
	// Defaults to "unpkg" when empty. Only "esm.sh" supports jsr: specifiers.
	CDN specifier.CDN

	// FetchTimeout is the maximum time to wait for a network fetch.
	// Defaults to DefaultTimeout when zero. Has no effect if Fetcher is nil.
	FetchTimeout time.Duration
}

Options configures how tokens are loaded.