theo

library8.1.5jsnpmunverified

Theo is a design tokens formatter and transformer library maintained by Salesforce UX. The latest stable version is 8.1.5, released on npm under an Apache-2.0 license. It provides a declarative way to convert design tokens defined in YAML/JSON into platform-specific formats such as SCSS, CSS custom properties, JavaScript, Swift, Android XML, etc. Key differentiators: supports custom transforms and formats, works with a variety of token file formats, and has a plugin system for additional build tool integrations (gulp). Note that starting from v6, the gulp plugin is distributed separately as gulp-theo.

devops

npm install theo

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · THEO

theo

devopsjavascriptv8.1.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

theo

✓ import theo from 'theo'

✗ const theo = require('theo')

Theo exports a default object with methods. CJS require is still supported, but ESM is recommended for modern setups.

convert

✓ theo.convert({...})

✗ theo.convert({...})

convert is a method on the default export, not a separate named export.

registerTransform

✓ theo.registerTransform('custom', [...])

✗ registerTransform('custom', [...])

Must be called on the theo object, not imported separately.

Shows how to convert a YAML design token string to SCSS using Theo's convert method with web transform and scss format.

import theo from 'theo'; import yaml from 'yaml'; // Sample design token file content in YAML: const tokensYaml = ` props: color_primary: value: "#3366FF" type: color category: brand `; // Convert to SCSS theo.convert({ transform: { type: 'web', data: yaml.parse(tokensYaml), }, format: { type: 'scss', }, }).then(result => { console.log(result); }).catch(err => { console.error(err); });

Debug

Known issues

breakingIn v6, the gulp plugin was removed from the main package and moved to gulp-theo. If you upgrade from v5 to v6+, you must install gulp-theo separately.

fix

npm install gulp-theo --save-dev and update your gulpfile to require 'gulp-theo' instead of accessing theo.gulp.

affects: >=6.0.0

gotchaTheo expects token files to be in YAML format by default. If you pass plain JSON, it may cause unexpected parsing errors. You must use the YAML parser (or register a custom parser) for JSON files.

fix

Use yaml.parse() on JSON content if you want to pass JSON data directly; otherwise, ensure your input file is valid YAML.

affects: *

gotchaCustom transforms must be registered before calling convert, otherwise they won't be available. If you use a transform name that doesn't exist, theo will throw an error.

fix

Call theo.registerTransform or theo.registerValueTransform before any convert calls.

affects: *

Errors

Common errors & fixes

TypeError: Cannot read property 'type' of undefined

The input data does not have a 'props' key or is malformed. Theo expects an object with a 'props' property containing token definitions.

fix

Ensure your tokens object has a top-level 'props' key: { props: { token_name: { value: '...', type: '...' } } }.

Theo: transform type 'xyz' not found

You are trying to use a transform type that has not been registered (e.g., 'xyz'). Theo's built-in transforms include 'raw', 'web', 'ios', 'android'.

fix

Use one of the built-in transform types or register a custom one with theo.registerTransform() before calling convert.

Theo: format type 'xyz' not found

You are trying to use a format type that has not been registered (e.g., 'xyz'). Built-in formats include 'custom-properties.css', 'cssmodules.css', 'scss', 'sass', 'less', 'stylus', 'json', 'js', 'mobile.json', 'aura', 'android.xml', etc.

fix

Use a valid format type name or register a custom format with theo.registerFormat() before calling convert.

Upgrade

Version history

8.1.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/salesforce-ux/theo ↗

packagetheo ↗

homepagehttps://github.com/salesforce-ux/theo ↗