Docs
Systhema Design (opens in new tab)
Unreleased

@systhemaui/core API

Token APIs, utility functions and runtime config accessors.

On this page

@systhemaui/core is the foundation of the Systhema framework: it processes your design tokens and powers @systhemaui/react, @systhemaui/next, and @systhemaui/payload. This page lists its runtime API. For what core does, see Design tokens.

pnpm add @systhemaui/core

The package comes from the private GitHub Packages registry. See Registry access.

Token APIsLink to this section

These read the token dataset directly and are server/build-time only — do not import them from 'use client' code. For build-time work with tokens, @systhemaui/core exports the same helpers it uses internally.

import {
  getTokens,
  getTokensConfig,
  getRasterizedTokens,
  getResolvedValue,
  getRow,
} from '@systhemaui/core'

getTokens()Link to this section

Returns the loaded tokens organised by collection (colorSystem, responsiveSizing, font, colorPrimitives, etc.).

const { colorSystem } = getTokens()
const colorModes = Object.keys(colorSystem || {}) // ['default', 'dark', ...]

getResolvedValue(target, path, mode, asString?)Link to this section

Resolve a token path against a specific mode. Used heavily inside @systhemaui/payload to derive UI options (e.g. building a color picker that previews each color mode).

import { getResolvedValue, getTokens } from '@systhemaui/core'

const { colorSystem } = getTokens()
const bg = getResolvedValue(colorSystem, 'layout.bg.default', 'dark', true) as string

getRow(path, target)Link to this section

Look up a row of values across all modes for a given path. Useful when you want to enumerate every variation a token has.

The values are CSS strings, and for any path a spacing rule matches they are Tailwind's spacing function — getRow('article.paddingX', responsiveSizing) is { sm: '--spacing(0 / 4)', md: '--spacing(60 / 4)', lg: '--spacing(88 / 4)' }. parseInt returns NaN on all three, so compare with resolveTokenPx(value, fallback) rather than parsing by hand:

import { getRow, getTokens, resolveTokenPx } from '@systhemaui/core'

const { responsiveSizing } = getTokens()
const row = getRow('article.paddingX', responsiveSizing)

Object.values(row).some((size) => resolveTokenPx(size as string, 0) > 0) // true

getRasterizedTokens()Link to this section

Returns a flattened, mode-aware token tree where references like {font.default.body.fontFamily} have been resolved.

Utility functionsLink to this section

import {
  docsUrl,
  deepMerge,
  deepMergeReplace,
  getFirstKey,
  isArray,
  isObject,
  optimizeCSS,
  toKebabCase,
  toSnakeCase,
  toTitleCase,
  toUrlCase,
} from '@systhemaui/core'

getFirstKey(obj)Link to this section

Get the first key from an object (useful for default/base values, since JSON token files preserve insertion order from Figma).

const colors = { primary: '#000', secondary: '#fff' }
getFirstKey(colors) // 'primary'
getFirstKey({})     // null

toKebabCase(str)Link to this section

toKebabCase('camelCase')      // 'camel-case'
toKebabCase('PascalCase')     // 'pascal-case'
toKebabCase('snake_case')     // 'snake-case'
toKebabCase('SCREAMING_CASE') // 'screaming-case'
toKebabCase('some text')      // 'some-text'

toUrlCase(str)Link to this section

URL-friendly kebab-case with diacritics normalised and special characters stripped.

toUrlCase('Hello World')      // 'hello-world'
toUrlCase('Café & Bar')       // 'cafe-bar'
toUrlCase('über cool!')       // 'uber-cool'
toUrlCase('100% Awesome!!!')  // '100-awesome'

toSnakeCase(str)Link to this section

toSnakeCase('camelCase')   // 'camel_case'
toSnakeCase('PascalCase')  // 'pascal_case'
toSnakeCase('kebab-case')  // 'kebab_case'
toSnakeCase('some text')   // 'some_text'

toTitleCase(str)Link to this section

toTitleCase('camelCase')   // 'Camel Case'
toTitleCase('kebab-case')  // 'Kebab Case'
toTitleCase('snake_case')  // 'Snake Case'
toTitleCase('some text')   // 'Some Text'

docsUrl(route, anchor?)Link to this section

Builds a public documentation URL for the installed core minor version, or /next/ for a prerelease. See Documentation URLs for the client-safe import and route format.

deepMerge(target, source)Link to this section

Deep merge with array concatenation. Objects are merged recursively; arrays are concatenated; primitives in source override target.

const target = { colors: { primary: 'blue' }, sizes: ['sm', 'md'], enabled: false }
const source = { colors: { secondary: 'red' }, sizes: ['lg', 'xl'], enabled: true }
deepMerge(target, source)
// { colors: { primary: 'blue', secondary: 'red' },
//   sizes: ['sm', 'md', 'lg', 'xl'],
//   enabled: true }

deepMergeReplace(target, source)Link to this section

Like deepMerge, but arrays in source replace arrays in target instead of concatenating.

const target = { colors: { primary: 'blue' }, sizes: ['sm', 'md'], enabled: false }
const source = { colors: { secondary: 'red' }, sizes: ['lg', 'xl'], enabled: true }
deepMergeReplace(target, source)
// { colors: { primary: 'blue', secondary: 'red' },
//   sizes: ['lg', 'xl'],   // replaced, not concatenated
//   enabled: true }

isObject(item) / isArray(item)Link to this section

isObject({})           // true
isObject({ a: 1 })     // true
isObject([])           // false (arrays are not objects in this check)
isObject(null)         // false

isArray([])            // true
isArray([1, 2, 3])     // true
isArray({})            // false

optimizeCSS(styles)Link to this section

Sort CSS-in-JS objects so CSS variables come first, then properties, then nested selectors. Useful when authoring a Tailwind plugin that consumes Systhema's CSS shape.

import { optimizeCSS } from '@systhemaui/core'

const styles = {
  '.button': {
    color: 'white',
    '--button-color': 'blue',
    padding: '1rem',
    '&:hover': {
      '--button-color': 'darkblue',
      opacity: 0.8,
    },
  },
}

const optimized = optimizeCSS(styles)
// {
//   '.button': {
//     '--button-color': 'blue',  // CSS variables first
//     color: 'white',            // properties next
//     padding: '1rem',
//     '&:hover': {               // nested selectors last
//       '--button-color': 'darkblue',
//       opacity: 0.8,
//     },
//   },
// }

The same export is also available at @systhemaui/core/utils for tree-shaking-friendly imports.

logger and terminalColorsLink to this section

A small terminal-color logger used by Systhema's CLIs. Re-exported so consumer code can match the framework's output style.

import { logger, terminalColors } from '@systhemaui/core'

logger.info('Building tokens…')
logger.success('Done.')
logger.warn('Heads up.')
logger.error('Boom.')
console.log(terminalColors.cyan('cyan text'))

Runtime configLink to this section

import {
  getSysthemaConfig,
  getSysthemaConfigSync,
  setSysthemaConfigSync,
} from '@systhemaui/core/config'

From a 'use client' module, import the same accessors from @systhemaui/core/client instead. See Client and server code.

getSysthemaConfigSync()Link to this section

Synchronous loader. Reads the config from disk on first call and caches it.

const config = getSysthemaConfigSync()
console.log(config.blocks?.header)

getSysthemaConfig()Link to this section

Async version of the same loader.

const config = await getSysthemaConfig()
console.log(config.spacing)

Both accept an optional forceReload boolean argument to bypass the cache.

setSysthemaConfigSync(config)Link to this section

Set the config in-memory. Useful in runtimes where filesystem access isn't available (browser, edge, tests).

import { setSysthemaConfigSync } from '@systhemaui/core/config'
import type { SysthemaConfig } from '@systhemaui/core'

const config: SysthemaConfig = { packages: { react: true } }
setSysthemaConfigSync(config)

getSysthemaCookieConsentConfig()Link to this section

Returns the resolved SysthemaCookieConsentConfig, or null when cookieConsent.enabled !== true. See Resolving the config for how the Node and browser implementations differ.

Other entry pointsLink to this section