Plugin Design Tokens API reference

Source information

• Package: @pikacss/plugin-design-tokens
• Generated from the exported surface and JSDoc in packages/plugin-design-tokens/src/index.ts.
• Source files: packages/plugin-design-tokens/src/index.ts

Package summary

W3C design tokens to CSS variables

Use Design Tokens plugin when you need conceptual usage guidance instead of exact symbol lookup.

Functions

designTokens()

PikaCSS engine plugin that converts design tokens (W3C Design Tokens JSON or design.md documents) into CSS variables.

Returns: EnginePlugin - An EnginePlugin that reads EngineConfig.designTokens, loads all token sources, and merges the resulting variables into EngineConfig.variables.

Remarks:

Tokens flow through the core variables system, so they inherit unused-pruning, autocomplete integration, and selector scoping. Loaded files are registered as engine config dependencies so integrations reload when a token file changes.

import { designTokens } from '@pikacss/plugin-design-tokens'

export default defineEngineConfig({
  plugins: [designTokens()],
  designTokens: {
    sources: ['./design.md'],
    themes: { dark: { selector: '.dark' } },
  },
})

parseDesignMarkdown(content)

Extracts design token blocks from a markdown design document.

Parameter	Type	Description
content	string	The markdown source (e.g. the content of a design.md file).

Returns: { base: DesignTokenGroup[], themeBlocks: ParsedThemeBlock[] } - The parsed base token groups and theme-scoped token blocks.

Remarks:

Only fenced code blocks whose info string starts with tokens are read; all other markdown content is ignored. The info string may carry theme=<name> and selector=<css-selector> attributes. Block content must be valid JSON in the W3C Design Tokens format; invalid blocks are skipped with a warning.

const { base, themeBlocks } = parseDesignMarkdown(await readFile('design.md', 'utf-8'))

tokenPathToVariableName(path, prefix?)

Converts a token path into its generated CSS variable name.

Parameter	Type	Description
path	string[]	The token path segments (e.g. ['color', 'primary']).
prefix?	string	Optional variable name prefix (without leading --).

Returns: --${string} - The CSS variable name including the -- prefix.

Remarks:

Each segment is kebab-cased (fontSize → font-size), then segments are joined with -. Alias references ({color.primary}) use the same normalization, so aliases always resolve to the emitted variable name.

tokenPathToVariableName(['color', 'primary'])          // '--color-primary'
tokenPathToVariableName(['font', 'size'], 'app')       // '--app-font-size'

Types

DesignToken

A design token node: an object carrying a $value plus optional metadata.

Property	Type	Description	Default
$value	DesignTokenValue	The token value. Strings may reference other tokens via {path.to.token}.	—
$type?	string	Optional token type (e.g. 'color', 'dimension', 'shadow', 'fontFamily').	—
$description?	string	Optional human-readable description.	—

const token: DesignToken = { $value: '#3b82f6', $type: 'color', $description: 'Primary brand color' }

DesignTokenGroup

A nested group of design tokens following the W3C Design Tokens format.

Remarks:

Keys are group or token names. A node with a $value property is a token; any other object is a nested group.

const tokens: DesignTokenGroup = {
  color: {
    primary: { $value: '#3b82f6', $type: 'color' },
    accent: { $value: '{color.primary}' },
  },
}

DesignTokensConfig

Configuration object for the designTokens engine option.

Property	Type	Description	Default
sources?	Arrayable<DesignTokensSource>	Base token sources emitted under :root. Later sources override earlier ones when names collide.	—
themes?	Record<string, DesignTokensTheme>	Theme overrides keyed by theme name. Tokens are emitted under the theme's selector.	—
prefix?	string	Prefix prepended to every generated CSS variable name (without leading --).	'' (no prefix)
root?	string	Base directory used to resolve relative source file paths.	process.cwd()
pruneUnused?	boolean	Pruning override applied to every generated variable. When unset, the variables config default applies.	undefined

const config: DesignTokensConfig = {
  sources: ['./design.md'],
  themes: { dark: { sources: ['./design.dark.tokens.json'] } },
}

DesignTokensSource

A design token source: an inline DesignTokenGroup object or a file path.

Remarks:

File paths ending in .md are parsed as design documents (tokens are read from ```tokens fenced code blocks). Any other extension is parsed as a W3C Design Tokens JSON file. Relative paths resolve against DesignTokensConfig.root.

DesignTokensTheme

Per-theme design token configuration.

Property	Type	Description	Default
selector?	string	The CSS selector scoping this theme's variables.	.${themeName}
sources?	Arrayable<DesignTokensSource>	Token sources providing this theme's overrides.	—

const dark: DesignTokensTheme = {
  selector: '[data-theme="dark"]',
  sources: { color: { primary: { $value: '#60a5fa' } } },
}

DesignTokenValue

A single design token value as defined by the W3C Design Tokens draft.

Remarks:

Strings may contain alias references in the form {path.to.token}, which are resolved to var(--path-to-token) in the generated CSS.

Module augmentations

EngineConfig (@pikacss/core)

Property	Type	Description	Default
designTokens?	DesignTokensConfig	Design tokens configuration. Tokens are converted to CSS variables via the variables system.	undefined

Next

• Design Tokens plugin
• ESLint Config API reference
• API reference overview