@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/JS (omitted)
├── tokens/
│   ├── tokens.json        # Source data (omitted)
│   ├── tokens.css         # CSS variables (generated & committed)
│   ├── tokens.ts          # TypeScript constants (generated & committed)
│   └── tokens.js          # Same constants as plain JS (generated & committed)
├── .env.example           # Required: FIGMA_API_TOKEN, FIGMA_FILE_ID
└── package.json

Syncing Tokens from Figma

Prerequisites

1. Have view access to the Taco tokens Figma file, and a Figma personal access token created from that account (Figma → Settings → Security → Personal access tokens, with file_content:read scope). Figma returns 404 Not Found for files your account can't see.

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

   FIGMA_API_TOKEN=your_token_here
   FIGMA_FILE_ID=your_file_id_here
   

   FIGMA_FILE_ID is only the key from the file URL, not the full URL. For https://www.figma.com/design/<FILE_ID>/Taco-tokens?node-id=0-1, use <FILE_ID>. Pasting the full URL also gives a 404.

3. Tokens are read from a page named exactly Export (case-sensitive), organized in frames/groups with TEXT nodes or color fills. If the fetch fails with Could not find Figma page "Export", check the page name or that you're using the right file.

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 + tokens/tokens.js

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
  • tokens/tokens.js - the same constants as plain JS, loaded at runtime (Node can't strip types from .ts under node_modules)
• Typography size tokens keep Figma source values in tokens.json (px), but text-* and heading-* are converted to rem in generated CSS/TS/JS outputs (base 16px).

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.js",
    "module": "./tokens/tokens.js",
    "types": "./tokens/tokens.ts",
    "exports": {
        ".": {
            "types": "./tokens/tokens.ts",
            "default": "./tokens/tokens.js"
        },
        "./tokens": {
            "types": "./tokens/tokens.ts",
            "default": "./tokens/tokens.js"
        },
        "./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