@economic/taco-tokens

This is the design tokens package for Taco and other consumers of the economic brand. Taco-tokens fetches tokens from Figma and converts them to CSS variables and TypeScript constants.

Overview

This package provides design tokens in multiple formats:

• CSS Variables - for use in stylesheets
• TypeScript Constants - for use in JavaScript/TypeScript and config files

Note: This is a standalone package that can be consumed directly, but most consumers will likely use @economic/taco which already includes and re-exports these tokens.

Installation & Usage

For consumers not using Taco

Recommended: Import directly from @economic/taco-tokens:

// CSS variables
import '@economic/taco-tokens/tokens.css';

// TypeScript constants
import { primaryColors, borderRadius, spacing } from '@economic/taco-tokens';

Package Structure

packages/taco-tokens/
├── scripts/
│   ├── fetch-tokens.ts    # Fetches tokens from Figma API (omitted)
│   └── build-tokens.ts    # Converts JSON to CSS/TS (omitted)
├── tokens/
│   ├── tokens.json        # Source data (omitted)
│   ├── tokens.css         # CSS variables (generated & committed)
│   └── tokens.ts          # TypeScript constants (generated & committed)
├── .env.example           # Required: FIGMA_API_TOKEN, FIGMA_FILE_ID
└── package.json

Syncing Tokens from Figma

Prerequisites

1. Create a .env file (see .env.example):

   FIGMA_API_TOKEN=your_token_here
   FIGMA_FILE_ID=your_file_id_here

2. Currently the Figma file has tokens organized in frames/groups with TEXT nodes or color fills.

Sync Command

Fetch from Figma and build all outputs:

cd packages/taco-tokens
npm run sync-tokens

This runs:

1. fetch-tokens - Pulls from Figma → tokens/tokens.json
2. build-tokens - Converts JSON → tokens/tokens.css + tokens/tokens.ts

Individual Scripts

Fetch only:

npm run fetch-tokens

• Reads Figma file via API (you'll need access to a token and the file)
• Extracts token values from TEXT nodes or fills
• Groups by frame name (e.g., "Primary Colors", "Spacing")
• Sorts by category order (see CATEGORY_ORDER in script)
• Outputs: tokens/tokens.json

Build only:

npm run build-tokens

• Reads: tokens/tokens.json
• Outputs:
  • tokens/tokens.css - CSS custom properties
  • tokens/tokens.ts - TypeScript constants with type safety

Token Categories

Generated tokens are grouped by category:

• Primary Colors - tacoBlue, tacoGray
• Secondary Colors - tacoRed, tacoYellow, tacoGreen
• Tertiary Colors - tacoPink, tacoPurple
• Brand Colors - tacoBrandMorning, tacoBrandNoon, tacoBrandSunset, tacoBrandMidnight
• Spacing - tacoSpacing0 through tacoSpacing12
• Typography - tacoWeightBold, tacoTextSm, tacoHeadingLg, etc.
• Border Radius - tacoRadius0 through tacoRadiusFull
• Border Width - tacoBorderWidth0 through tacoBorderWidth2

Integration with Taco

How Taco Consumes Tokens

In packages/taco/src/index.tsx:

// Import CSS
import '@economic/taco-tokens/tokens.css';

// Re-export TypeScript constants
export * from '@economic/taco-tokens/tokens';

This means:

• ✅ CSS variables are automatically included in taco.css
• ✅ TypeScript constants are re-exported from @economic/taco
• ✅ Consumers get everything through a single package

Tailwind Integration

The Taco Tailwind config imports and uses the TypeScript token constants directly:

// packages/taco/tailwind.config.js
import { borderRadius } from '@economic/taco-tokens/tokens';

module.exports = {
    theme: {
        extend: {
            borderRadius: {
                DEFAULT: borderRadius.tacoRadius4,
                none: borderRadius.tacoRadius0,
                sm: borderRadius.tacoRadius2,
                lg: borderRadius.tacoRadius8,
                xl: borderRadius.tacoRadius12,
                full: borderRadius.tacoRadiusFull,
            },
        },
    },
};

This compiles the actual values (e.g., 4px, 8px) directly into the CSS at build time for better performance.

Publishing

This package is published separately from @economic/taco:

# From packages/taco-tokens
npm publish

Version strategy:

• @economic/taco-tokens has independent versioning
• @economic/taco specifies which version to consume

Access control:

• "private": false - package can be published
• Scoped package @economic/... - restricted to organization by default

Package Exports

{
    "main": "./tokens/tokens.ts",
    "module": "./tokens/tokens.ts",
    "types": "./tokens/tokens.ts",
    "exports": {
        ".": {
            "import": "./tokens/tokens.ts",
            "types": "./tokens/tokens.ts"
        },
        "./tokens": "./tokens/tokens.ts",
        "./tokens.css": "./tokens/tokens.css"
    }
}

Available imports:

// Main export (using default "." export)
import { tokens, primaryColors, spacing } from '@economic/taco-tokens';

// Explicit tokens path
import { tokens, primaryColors, spacing } from '@economic/taco-tokens/tokens';

// CSS
import '@economic/taco-tokens/tokens.css';

Consumer Examples

CSS Only

/* In your stylesheet */
.my-component {
    color: var(--taco-blue-500);
    padding: var(--taco-spacing-4);
    border-radius: var(--taco-radius-8);
}

TypeScript/JavaScript

import { primaryColors, spacing } from '@economic/taco';

const styles = {
    color: primaryColors.tacoBlue500,
    padding: spacing.tacoSpacing4,
};

Tailwind

// Maps to tailwind utility classes via. the tailwind.config
<div className="rounded-lg text-blue-500">Content</div>

Token Naming Convention

Pattern: taco[Category][Scale]

• Primary colors: tacoBlue100, tacoBlue500, tacoBlue900
• Spacing: tacoSpacing0, tacoSpacing1, ..., tacoSpacing12
• Typography: tacoTextSm, tacoTextMd, tacoHeadingLg
• Border radius: tacoRadius0, tacoRadius4, tacoRadiusFull

CSS variables: Kebab-case with -- prefix

--taco-blue-500
--taco-spacing-4
--taco-radius-8

TypeScript: camelCase

tacoBlue500;
tacoSpacing4;
tacoRadius8;

Troubleshooting

CSS variables not working?

• Ensure @economic/taco/taco.css is imported before usage
• Check browser DevTools → Elements → Computed → look for CSS variables

TypeScript imports failing?

• Run npm install from root to ensure workspace links are created
• Check node_modules/@economic/taco-tokens exists

Figma fetch failing?

• Verify .env has correct FIGMA_API_TOKEN and FIGMA_FILE_ID
• Check token has access to the Figma file
• Ensure Figma file structure matches expected format
• Ensure you're not hitting a rate limit