API Reference

This page lists the public APIs exported by the GenomeJS packages.

Use the linked pages for detailed examples, lifecycle behavior, errors, and implementation notes.

Packages

Package	Purpose
`@genomejs/core`	Framework-neutral compiler, runtime, utilities, errors, and types
`@genomejs/react`	React trait subscription hook
`@genomejs/vue`	Vue trait subscription composable
`@genomejs/svelte`	Svelte 5 rune-aware trait wrapper

Core imports

import {
  Genome,
  CircularDependencyError,
  UnresolvedTokenError,
  contrastRatio,
  lockContrast,
  fluidScale,
  bindMediaQueries,
  bindContainerSize,
} from "@genomejs/core";

import type {
  Primitive,
  RuntimeContext,
  DNAReader,
  TokenFn,
  TokenDefinition,
  GenomeConfig,
  Mutator,
} from "@genomejs/core";

`Genome`

The central compiler and runtime class.

new Genome(
  config: GenomeConfig,
  target?: HTMLElement | null,
): Genome

A browser instance defaults to:

document.documentElement;

When document is unavailable, the default target is:

null;

const genome = new Genome({
  primitives: {
    baseSpacing: 16,
  },

  tokens: {
    spacing: (dna, context) => {
      const scale = typeof context.scale === "number" ? context.scale : 1;

      return `${Number(dna.baseSpacing) * scale}px`;
    },
  },
});

Detailed reference:

`Genome` methods

`mutate()`

genome.mutate(
  patch: RuntimeContext,
): void

Shallowly merges a runtime-context patch, resolves derived tokens, expresses changed CSS custom properties, and notifies subscribers.

genome.mutate({
  mode: "dark",
  scale: 1.25,
});

Detailed reference:

`getTrait()`

genome.getTrait(
  name: string,
): Primitive

Returns the current resolved value of a primitive or derived token.

const spacing = genome.getTrait("spacing");

An unknown name throws a standard Error.

Detailed reference:

getTrait()

genome.subscribe(
  listener: () => void,
): () => void

Registers a listener and returns an unsubscribe function.

const unsubscribe = genome.subscribe(() => {
  console.log(genome.getTrait("spacing"));
});

unsubscribe();

Detailed reference:

subscribe()

`scope()`

genome.scope(
  target: HTMLElement,
  overrides?: RuntimeContext,
): Genome

Creates an independent child Genome using the same token configuration, another target, and optional initial context overrides.

const child = genome.scope(element, {
  density: "compact",
});

Detailed reference:

Contrast utilities

`contrastRatio()`

contrastRatio(
  hexA: string,
  hexB: string,
): number

Calculates relative-luminance contrast between two hexadecimal RGB colors.

const ratio = contrastRatio("#000000", "#ffffff");

Detailed reference:

contrastRatio()

`lockContrast()`

lockContrast(
  foreground: string,
  background: string,
  minRatio?: number,
): string

Returns the original foreground when it already satisfies the requested ratio. Otherwise, it adjusts the foreground toward black or white.

Default ratio:

4.5;

const foreground = lockContrast("#777777", "#888888", 4.5);

Detailed reference:

Typography utility

`fluidScale()`

fluidScale(
  minPx: number,
  maxPx: number,
  minVw?: number,
  maxVw?: number,
): string

Defaults:

minVw = 320;
maxVw = 1440;

Returns a CSS clamp() expression.

const headingSize = fluidScale(36, 72);

Detailed reference:

Browser environment bindings

`bindMediaQueries()`

bindMediaQueries(
  genome: Genome,
): () => void

Synchronizes these context properties:

{
  colorScheme: "light" | "dark";

  reducedMotion: boolean;
}

const cleanup = bindMediaQueries(genome);

The returned function removes both media-query listeners.

Detailed reference:

`bindContainerSize()`

bindContainerSize(
  genome: Genome,
  element: HTMLElement,
): () => void

Synchronizes:

{
  containerWidth: entry.contentRect.width;
}

const cleanup = bindContainerSize(genome, element);

The returned function disconnects the ResizeObserver.

Detailed reference:

Error classes

`CircularDependencyError`

new CircularDependencyError(
  cycle: string[],
)

Public property:

error.cycle;

Example message:

Circular token dependency: first -> second -> first

Detailed reference:

Error Reference

`UnresolvedTokenError`

new UnresolvedTokenError(
  token: string,
  missing: string[],
)

Public properties:

error.token;
error.missing;

Example message:

Token "surface" references undefined token(s): missingSurface

Detailed reference:

Error Reference

Core TypeScript types

`Primitive`

type Primitive = string | number;

`RuntimeContext`

interface RuntimeContext {
  [key: string]: unknown;
}

`DNAReader`

type DNAReader = Record<string, Primitive>;

`TokenFn`

type TokenFn = (dna: DNAReader, context: RuntimeContext) => Primitive;

`TokenDefinition`

type TokenDefinition = Primitive | TokenFn;

`GenomeConfig`

interface GenomeConfig {
  primitives: Record<string, Primitive>;

  tokens: Record<string, TokenDefinition>;
}

`Mutator`

type Mutator = RuntimeContext;

Detailed reference:

TypeScript Types

React adapter

Install:

npm install @genomejs/core @genomejs/react

Import:

import { useGenomeTrait } from "@genomejs/react";

Signature:

useGenomeTrait(
  genome: Genome,
  name: string,
): Primitive

const color = useGenomeTrait(genome, "color");

The adapter uses React’s external-store API to subscribe and read browser and server snapshots.

Detailed reference:

React

Vue adapter

Install:

npm install @genomejs/core @genomejs/vue

Import:

import { useGenomeTrait } from "@genomejs/vue";

Signature:

useGenomeTrait(
  genome: Genome,
  name: string,
): Ref<Primitive>

const color = useGenomeTrait(genome, "color");

The composable subscribes after mounting and cleans up when the component unmounts.

Detailed reference:

Svelte adapter

Install:

npm install @genomejs/core @genomejs/svelte

Import:

import { genomeTrait } from "@genomejs/svelte";

Conceptual signature:

genomeTrait(
  genome: Genome,
  name: string,
): {
  readonly value: Primitive;
}

const color = genomeTrait(genome, "color");

Read:

{color.value}

The adapter uses Svelte 5 runes and requires a Svelte-aware downstream compiler.

Detailed reference:

Svelte

Package export summary

`@genomejs/core`

Runtime exports:

Genome
CircularDependencyError
UnresolvedTokenError
contrastRatio
lockContrast
fluidScale
bindMediaQueries
bindContainerSize

Type exports:

Primitive
RuntimeContext
DNAReader
TokenFn
TokenDefinition
GenomeConfig
Mutator

`@genomejs/react`

useGenomeTrait

`@genomejs/vue`

useGenomeTrait

`@genomejs/svelte`

genomeTrait

API Reference

On this page