Package Exports

@recursica/common

Readme

@recursica/common

Shared utility functions and type guards for Recursica design token processing.

Overview

This package provides utility functions for processing, parsing, and detecting design tokens within the Recursica ecosystem. It includes type guards for token detection, parsers for converting design token values, and string utilities for code generation.

Installation

npm install @recursica/common

Usage

Importing All Utilities

import * from '@recursica/common';

Importing Specific Categories

// Type guards and detectors
import {
  isFontFamilyToken,
  isEffectToken,
  isColorOrFloatToken,
} from "@recursica/common";

// Token parsers
import { rgbToHex, toFontWeight } from "@recursica/common";

// String utilities
import { autoGeneratedFile, capitalize } from "@recursica/common";

API Reference

Type Guards (`detectors.ts`)

Type guard functions to detect different types of design tokens based on the @recursica/schemas package.

`isFontFamilyToken(token: CollectionToken): token is FontFamilyToken`

Checks if a token is a FontFamilyToken by verifying the presence of fontFamily and variableName properties.

import { isFontFamilyToken } from "@recursica/common";

if (isFontFamilyToken(token)) {
  // token is now typed as FontFamilyToken
  console.log(token.fontFamily, token.variableName);
}

`isEffectToken(token: CollectionToken): token is EffectToken`

Checks if a token is an EffectToken by verifying the presence of effects and variableName properties.

import { isEffectToken } from "@recursica/common";

if (isEffectToken(token)) {
  // token is now typed as EffectToken
  console.log(token.effects, token.variableName);
}

`isColorOrFloatToken(token: CollectionToken): token is Token`

Checks if a token is a basic Token (color or float) by verifying the presence of mode, type, name, and value properties.

import { isColorOrFloatToken } from "@recursica/common";

if (isColorOrFloatToken(token)) {
  // token is now typed as Token
  console.log(token.mode, token.type, token.name, token.value);
}

Parsers (`parsers/`)

Utility functions for converting and parsing design token values.

`rgbToHex(rgba: RGBA): string`

Converts an RGBA object to a HEX string or RGBA string if alpha is not 1.

import { rgbToHex } from "@recursica/common";

// Convert to HEX
const hex = rgbToHex({ r: 0.5, g: 0.8, b: 0.2, a: 1 });
// Returns: "#80cc33"

// Convert to RGBA string (when alpha < 1)
const rgba = rgbToHex({ r: 0.5, g: 0.8, b: 0.2, a: 0.5 });
// Returns: "rgba(128, 204, 51, 0.5000)"

`toFontWeight(value: string): number`

Converts font weight names to their numeric equivalents based on CSS font-weight values.

import { toFontWeight } from "@recursica/common";

console.log(toFontWeight("thin")); // 100
console.log(toFontWeight("light")); // 300
console.log(toFontWeight("regular")); // 400
console.log(toFontWeight("medium")); // 500
console.log(toFontWeight("bold")); // 700
console.log(toFontWeight("black")); // 900
console.log(toFontWeight("unknown")); // 400 (default)

Supported font weights:

thin → 100
extralight → 200
light → 300
regular → 400
medium → 500
semibold → 600
bold → 700
extrabold, extra bold → 800
black, heavy → 900

String Utilities (`strings/`)

Utility functions for string manipulation and code generation.

`autoGeneratedFile(): string`

Returns a standard header comment for auto-generated files.

import { autoGeneratedFile } from "@recursica/common";

const header = autoGeneratedFile();
console.log(header);
/*
/* prettier-ignore */
/* eslint-disable */
/* tslint:disable */
/*
Auto-generated by Recursica.
Do NOT edit these files directly

For more information about Recursica, go to https://recursica.com
*/

`capitalize(str: string): string`

Capitalizes each word in a string and replaces dashes with spaces.

import { capitalize } from "@recursica/common";

console.log(capitalize("hello-world")); // "Hello World"
console.log(capitalize("my-awesome-component")); // "My Awesome Component"

Examples

Processing Design Tokens

import {
  isFontFamilyToken,
  isColorOrFloatToken,
  rgbToHex,
  toFontWeight,
} from "@recursica/common";

function processTokens(tokens: CollectionToken[]) {
  return tokens.map((token) => {
    if (isFontFamilyToken(token)) {
      return {
        ...token,
        fontWeight: toFontWeight(token.fontFamily),
      };
    }

    if (isColorOrFloatToken(token) && token.type === "color") {
      return {
        ...token,
        hexValue: rgbToHex(token.value as RGBA),
      };
    }

    return token;
  });
}

Generating Code Files

import { autoGeneratedFile, capitalize } from "@recursica/common";

function generateThemeFile(themeName: string, tokens: any[]) {
  const header = autoGeneratedFile();
  const displayName = capitalize(themeName);

  return `${header}

export const ${displayName}Theme = {
  // Generated theme content
};`;
}

Development

Building

npm run build

Type Checking

npm run check-types

Linting

npm run lint

Development Mode

npm run dev

Dependencies

This package depends on:

@recursica/schemas - For TypeScript interfaces and types used in type guards

Contributing

When adding new utilities:

Place them in the appropriate category (detectors.ts, parsers/, or strings/)
If creating a new category, add a new file and export it from index.ts
Add comprehensive JSDoc documentation
Include examples in this README
Ensure functions are pure and have predictable behavior
Add appropriate type guards and error handling

License

MIT