@pixelscriptio/tessera/tokens

Token parsing, resolution, CSS output and the runtime theme API. See Tokens.

AttributeTarget

interface

Theme switching only sets a data-* attribute; the CSS custom properties do the rest, so nothing re-renders. The target is anything with attribute methods, so this file does not depend on the DOM.

export interface AttributeTarget {
  getAttribute(name: string): string | null
  setAttribute(name: string, value: string): void
  removeAttribute(name: string): void
}

BuildInput

interface

Not documented yet.

export interface BuildInput {
  
  baseName?: string
  base: TokenFileInput[]
  themes?: TokenFileInput[]
}

BuildResult

interface

Not documented yet.

export interface BuildResult {
  ok: boolean
  diagnostics: TokenDiagnostic[]
  
  css: string
  dts: string
  manifest: TokenManifest | undefined
}

buildTokens

function

Not documented yet.

function buildTokens(input: BuildInput): BuildResult

Color

interface

Not documented yet.

export interface Color {
  space: ColorSpace
  
  components: [number, number, number]
  alpha: number
}

colorDistance

function

Perceptual distance: Euclidean distance in OKLab. About 0.02 is just noticeable.

function colorDistance(a: Color, b: Color): number

ColorSpace

type

Color parsing and math for the style checks: which design token is nearest to a raw color, and what the WCAG contrast ratio of two colors is. It reads the CSS color strings that the token build emits (hex, rgb, hsl, hwb, lab, lch, oklab, oklch, color()) and the literals authors write, including names. No dependencies and no DOM, so it runs in a browser.

export type ColorSpace =
  | 'srgb'
  | 'srgb-linear'
  | 'display-p3'
  | 'a98-rgb'
  | 'prophoto-rgb'
  | 'rec2020'
  | 'xyz-d50'
  | 'xyz-d65'
  | 'lab'
  | 'lch'
  | 'oklab'
  | 'oklch'
  | 'hsl'
  | 'hwb'

composite

function

color drawn over an opaque backdrop.

function composite(color: Color, backdrop: Color): Color

contrastPairs

function

Pairs of tokens a person would put text on: the text and bg siblings of a group (color.action.primary.text on color.action.primary.bg), and every color.text.* on every color.surface.*. The ratio is measured in every scope that has both, from the value after aliases are followed.

function contrastPairs(manifest: TokenManifest | undefined, minimum: number): ContrastRow[]

contrastRatio

function

WCAG 2 contrast ratio between two colors, from 1 to 21. A translucent foreground is drawn over the background.

function contrastRatio(foreground: Color, background: Color): number

ContrastRow

interface

Not documented yet.

export interface ContrastRow {
  scope: string
  foreground: string
  background: string
  ratio: number
  
  passes: boolean
}

cssVarName

function

CSS custom property name for a token path: --t-color-action-primary-bg. $root is dropped.

function cssVarName(path: string): string

detectFormat

function

Detect what a set of files is, if the caller did not say.

function detectFormat(files: InterchangeFile[]): InterchangeFormat

ExportResult

interface

Not documented yet.

export interface ExportResult {
  files: InterchangeFile[]
  diagnostics: TokenDiagnostic[]
}

exportTokens

function

Write the tokens in a form other tools read. dtcg: strict DTCG 2025.10 token files plus a Resolver document (tessera.resolver.json) that lists the base as a set and each attribute (theme, density) as a modifier with one context per theme. tokens-studio: the multi-file layout of Tokens Studio (one file per set, $themes.json, $metadata.json) with values as the strings that plugin reads.

function exportTokens(input: BuildInput, format: InterchangeFormat): ExportResult

formatDiagnostic

function

Same layout as the compiler errors in the spec (section 11), with the token path in place of line:column.

function formatDiagnostic(d: TokenDiagnostic): string

getDensity

function

Not documented yet.

function getDensity(target?: AttributeTarget): string | null

getTheme

function

Not documented yet.

function getTheme(target?: AttributeTarget): string | null

ImportResult

interface

Not documented yet.

export interface ImportResult {
  
  base: InterchangeFile[]
  
  themes: InterchangeFile[]
  
  diagnostics: TokenDiagnostic[]
}

importTokens

function

Import tokens from files written by Tokens Studio or Penpot, strict DTCG, or a DTCG Resolver document.

function importTokens(files: InterchangeFile[], format?: InterchangeFormat | "auto"): ImportResult

InterchangeFile

interface

A file the importer reads or the exporter writes. Paths use forward slashes.

export interface InterchangeFile {
  path: string
  content: string
}

InterchangeFormat

type

Not documented yet.

export type InterchangeFormat = 'dtcg' | 'tokens-studio'

isColorFunction

function

Names of the CSS functions that write a color literal.

function isColorFunction(name: string): boolean

ManifestTheme

interface

Not documented yet.

export interface ManifestTheme {
  attribute: string
  name: string
  file: string
  
  auto?: string
  overrides: string[]
}

ManifestToken

interface

Not documented yet.

export interface ManifestToken {
  path: string
  cssVar: string
  type: string
  tier: TokenTier
  description?: string
  extensions?: Record<string, unknown>
  
  values: Record<string, ManifestValue>
}

ManifestValue

interface

Not documented yet.

export interface ManifestValue {
  
  css: string
  
  resolved: string
  
  alias?: string
}

NAMED_COLORS

constant

Not documented yet.

const NAMED_COLORS: Readonly<Record<string, string>>

parseCssColor

function

Parse a CSS color value. Returns undefined for anything that is not a recognised color literal.

function parseCssColor(input: string): Color | undefined

resolverRefs

function

The files a Resolver document refers to, so a caller can read them before importing.

function resolverRefs(content: string): string[]

setDensity

function

Not documented yet.

function setDensity(name: string | null, target?: AttributeTarget): void

setTheme

function

Not documented yet.

function setTheme(name: string | null, target?: AttributeTarget): void

SUPPORTED_TYPES

constant

Not documented yet.

const SUPPORTED_TYPES: readonly ["color", "dimension", "duration", "number", "fontFamily", "fontWeight", "cubicBezier", "strokeStyle", "shadow", "border", "transition"]

toHex

function

Not documented yet.

function toHex(color: Color): string

TOKEN_CODES

constant

Not documented yet.

const TOKEN_CODES: { readonly T1001: "Invalid token file"; readonly T1002: "Invalid token name"; readonly T1003: "Missing token type"; readonly T1004: "Unsupported token type"; readonly T1005: "Invalid token value"; readonly T1006: "Unknown token reference"; readonly T1007: "Circular token reference"; readonly T1008: "Token reference has the wrong type"; readonly T1009: "Unsupported DTCG feature"; readonly T1010: "Theme extends the wrong base"; readonly T1011: "Theme adds a new token name"; readonly T1012: "Theme changes a token type"; readonly T1013: "Duplicate token"; readonly T1014: "Invalid theme file"; readonly T1015: "Duplicate theme"; readonly T1016: "Import skipped or adjusted something"; readonly T1017: "Cannot read the import"; }

TokenCode

type

Not documented yet.

export type TokenCode = keyof typeof TOKEN_CODES

TokenDiagnostic

interface

Not documented yet.

export interface TokenDiagnostic {
  code: TokenCode
  severity: 'error' | 'warning'
  message: string
  
  hint?: string
  file?: string
  
  path?: string
}

TokenFileInput

interface

Not documented yet.

export interface TokenFileInput {
  
  file: string
  
  content: unknown
}

TokenManifest

interface

Not documented yet.

export interface TokenManifest {
  version: 1
  base: string
  tokens: ManifestToken[]
  themes: ManifestTheme[]
}

TokenTier

type

Not documented yet.

export type TokenTier = 'primitive' | 'semantic' | 'component'

toOklab

function

Not documented yet.

function toOklab(color: Color): Vec

toSrgb

function

Gamma-encoded sRGB clamped to the displayable range.

function toSrgb(color: Color): Vec