@pantograph/tokens

Pantograph Design Tokens

Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. They're used in place of hard-coded values (such as hex values for color or pixel values for spacing) to maintain a scalable and consistent visual system for UI development.

This package contains CSS tokens that synchronize design (Figma) and development, ensuring consistency across all platforms and implementations.

Token Naming Convention

All tokens are mapped to use the --pt-* prefix for easy usage, regardless of their original prefix in the JSON files. This provides a consistent and simple API for developers.

• All tokens: --pt-* (Pantograph Token)
• No need to remember different prefixes - everything uses --pt-*

Token Categories

Colors

Alpha Colors

Transparency values for overlays and effects:

Token Name	Value	Description
--pt-alpha-gray-0	rgba(0, 0, 0, 0)	Transparent
--pt-alpha-gray-1	rgba(0, 0, 0, 0.04)	4% opacity
--pt-alpha-gray-2	rgba(0, 0, 0, 0.08)	8% opacity
--pt-alpha-gray-3	rgba(0, 0, 0, 0.24)	24% opacity
--pt-alpha-gray-4	rgba(0, 0, 0, 0.4)	40% opacity
--pt-alpha-gray-5	rgba(0, 0, 0, 0.64)	64% opacity

Primitive Colors

Complete primitive color palette with all color families:

Alpha Colors:

• --pt-alpha-gray-0 to --pt-alpha-gray-5 (transparency values)

Amber Colors:

• --pt-amber-0 to --pt-amber-9 (lightest to darkest)

Amethyst Colors:

• --pt-amethyst-0 to --pt-amethyst-9 (lightest to darkest)

Blue Colors:

• --pt-blue-0 to --pt-blue-9 (lightest to darkest)

Cyan Colors:

• --pt-cyan-0 to --pt-cyan-9 (lightest to darkest)

Fuchsia Colors:

• --pt-fuchsia-0 to --pt-fuchsia-9 (lightest to darkest)

Gray Colors:

• --pt-gray-0, --pt-gray-05, --pt-gray-1 to --pt-gray-10 (lightest to darkest)

Green Colors:

• --pt-green-0 to --pt-green-9 (lightest to darkest)

Lime Colors:

• --pt-lime-0 to --pt-lime-9 (lightest to darkest, note: --pt-lime-6 is missing)

Mallard Colors:

• --pt-mallard-0 to --pt-mallard-9 (lightest to darkest)

Ocean Colors:

• --pt-ocean-0 to --pt-ocean-9 (lightest to darkest)

Orange Colors:

• --pt-orange-0 to --pt-orange-9 (lightest to darkest)

Pink Colors:

• --pt-pink-0 to --pt-pink-9 (lightest to darkest)

Red Colors:

• --pt-red-0 to --pt-red-9 (lightest to darkest)

Sky Colors:

• --pt-sky-0 to --pt-sky-9 (lightest to darkest)

Teal Colors:

• --pt-teal-0 to --pt-teal-9 (lightest to darkest)

Violet Colors:

• --pt-violet-0 to --pt-violet-9 (lightest to darkest)

Yellow Colors:

• --pt-yellow-0 to --pt-yellow-9 (lightest to darkest)

Semantic Color Tokens

Pre-configured semantic color tokens with complete state variants:

Blue Tokens:

• --pt-blue-br - Primary blue border
• --pt-blue-br-subtle - Light blue border
• --pt-blue-br-subtle-target - Hover state
• --pt-blue-br-subtle-trigger - Active state
• --pt-blue-br-target - Dark blue border
• --pt-blue-br-trigger - Darkest blue border
• --pt-blue-fg - Blue foreground
• --pt-blue-fg-subtle - Light blue foreground
• --pt-blue-fill - Blue fill
• --pt-blue-fill-subtle - Light blue fill

Gray Tokens:

• --pt-gray-br - Gray border
• --pt-gray-br-subtle - Light gray border
• --pt-gray-fg - Gray foreground
• --pt-gray-fg-subtle - Light gray foreground
• --pt-gray-fill - Gray fill
• --pt-gray-fill-subtle - Light gray fill

Primary Tokens:

• --pt-primary-br - Primary border
• --pt-primary-fg - Primary foreground
• --pt-primary-fill - Primary fill
• --pt-primary-oncolor - Text color on primary backgrounds

Status Tokens:

• --pt-danger-* - Error/danger colors
• --pt-success-* - Success colors
• --pt-warning-* - Warning colors
• --pt-info-* - Information colors
• --pt-disable-* - Disabled state colors

Theme Classes

Themes are applied via CSS classes that change token values:

Light Theme:

.pantograph-light {
  /* Light mode color values */
}

Dark Theme:

.pantograph-dark {
  /* Dark mode color values */
}

Brand Themes:

.oktuple-theme { /* Ocean blue primary colors */ }
.claytap-theme { /* Sky blue primary colors */ }
.agility-theme { /* Mallard green primary colors */ }
.pantograph-theme { /* Blue primary colors */ }
.bounteco-theme { /* Amethyst purple primary colors */ }

Gray Scale Themes:

.pantograph-arsenic { /* Arsenic gray scale */ }
.pantograph-cool { /* Cool gray scale */ }
.pantograph-warm { /* Warm gray scale */ }
.pantograph-neutral { /* Neutral gray scale */ }

Spacing & Dimensions

Spacing Scale

Token Name	Value	Usage
--pt-space-0	0px	No spacing
--pt-space-100	2px	Micro spacing
--pt-space-200	4px	Small spacing
--pt-space-300	6px	Small-medium spacing
--pt-space-400	8px	Medium spacing
--pt-space-600	12px	Large spacing
--pt-space-800	16px	Extra large spacing
--pt-space-1000	20px	Huge spacing
--pt-space-1200	24px	Huge spacing
--pt-space-1600	32px	Massive spacing
--pt-space-2000	40px	Massive spacing
--pt-space-2400	48px	Massive spacing
--pt-space-2800	56px	Massive spacing
--pt-space-3200	64px	Massive spacing
--pt-space-4000	80px	Massive spacing
--pt-space-4800	96px	Massive spacing

Size Scale

Token Name	Value	Usage
--pt-size-3xsm	14px	Extra small
--pt-size-2xsm	16px	Very small
--pt-size-xsm	20px	Small
--pt-size-sm	24px	Small-medium
--pt-size-md	32px	Medium
--pt-size-lg	40px	Large
--pt-size-xlg	48px	Extra large
--pt-size-2xlg	56px	Very large
--pt-size-3xlg	80px	Huge

Border Radius

Token Name	Value	Usage
--pt-roundness-zero	0px	No radius
--pt-roundness-sm	4px	Small radius
--pt-roundness-md	6px	Medium radius
--pt-roundness-lg	8px	Large radius
--pt-roundness-xlg	12px	Extra large radius
--pt-roundness-full	88px	Full radius (circular)

Stroke Width

Token Name	Value	Usage
--pt-stroke-0	0px	No stroke
--pt-stroke-10	1px	Thin stroke
--pt-stroke-15	1.5px	Thin-medium stroke
--pt-stroke-20	2px	Medium stroke
--pt-stroke-30	3px	Thick stroke
--pt-stroke-40	4px	Very thick stroke

Screen Dimensions

Token Name	Value	Usage
--pt-screen-min-height	1024px	Minimum screen height
--pt-screen-min-width	1440px	Minimum screen width
--pt-screen-max-width	1920px	Maximum screen width

Typography

Font Family

Font families are applied via CSS classes:

Persian Text:

.fa, [lang="fa"] {
  --pt-font-family: notocoloremoji, iranyekan, inter, tahoma, serif;
}

English Text:

.en, [lang="en"] {
  --pt-font-family: notocoloremoji, inter, tahoma, serif;
}

Font Weights

Token Name	Value	Usage
--pt-font-weight-bold	bold	Bold text
--pt-font-weight-medium	medium	Medium weight
--pt-font-weight-regular	regular	Regular weight

Line Heights

Line heights are applied via CSS classes:

Title Line Heights:

.title, .pantograph-tokens {
  --pt-lineheight-1: 38px;
  --pt-lineheight-2: 28px;
  --pt-lineheight-3: 24px;
  --pt-lineheight-4: 20px;
  --pt-lineheight-5: 18px;
  --pt-lineheight-6: 16px;
  --pt-lineheight-7: 14px;
  --pt-lineheight-8: 12px;
}

Paragraph Line Heights:

.paragraph {
  --pt-lineheight-1: 48px;
  --pt-lineheight-2: 32px;
  --pt-lineheight-3: 24px;
  --pt-lineheight-4: 24px;
  --pt-lineheight-5: 28px;
  --pt-lineheight-6: 24px;
  --pt-lineheight-7: 20px;
  --pt-lineheight-8: 18px;
}

Levels (Indentation)

Level System

The level system provides dynamic indentation based on nesting depth:

Token Name	Value	Usage
--pt-level	0	Current nesting level
--pt-level-padding-sm	calc(4px + 20px * level)	Small indentation
--pt-level-padding-md	calc(8px + 24px * level)	Medium indentation
--pt-level-padding-lg	calc(12px + 28px * level)	Large indentation
--pt-level-gap-sm	4px	Small gap
--pt-level-gap-md	4px	Medium gap
--pt-level-gap-lg	8px	Large gap

Icons

Icon Classes

Icons are sized using CSS classes:

Class Name	Size	Stroke	Usage
.pc_icon--3xsm	14px	1px	Extra small icons
.pc_icon--2xsm	16px	1px	Very small icons
.pc_icon--xsm	20px	1px	Small icons
.pc_icon--sm	24px	1.5px	Small-medium icons

Icon Tokens

Token Name	Value	Usage
--pt-icon-size	var(--pt-size-*)	Icon size
--pt-icon-stroke	var(--pt-stroke-*)	Icon stroke width

Usage

Installation

npm install @pantograph/tokens

CSS Custom Properties

Import the font faces CSS file in your project:

@import '@pantograph/tokens/style/index.css';

Then use the tokens in your CSS:

.my-component {
  background-color: rgba(var(--pt-blue-5));
  padding: var(--pt-space-400);
  border-radius: var(--pt-roundness-lg);
  color: rgba(var(--pt-gray-8));
  border: var(--pt-stroke-10) solid rgba(var(--pt-gray-2));
}

Theme Application

Apply themes using CSS classes on your root element:

<!-- Light theme with Pantograph brand -->
<div class="pantograph-tokens pantograph-light pantograph-theme">
  <div class="pantograph-neutral">
    <p>Content with light theme and neutral gray scale</p>
  </div>
</div>

<!-- Dark theme with OKTUPLE brand -->
<div class="pantograph-tokens pantograph-dark oktuple-theme">
  <div class="pantograph-arsenic">
    <p>Content with dark theme and arsenic gray scale</p>
  </div>
</div>

Language Support

Apply language-specific font families:

<!-- Persian text -->
<div class="fa" lang="fa">
  <p>Persian text with Iran Yekan font</p>
</div>

<!-- English text -->
<div class="en" lang="en">
  <p>English text with Inter font</p>
</div>

Icon Usage

Use icon classes for consistent icon sizing:

<!-- Small icon -->
<i class="pc_icon--3xsm">icon</i>

<!-- Medium icon -->
<i class="pc_icon--sm">icon</i>

Level System

Use the level system for dynamic indentation. You can either use raw variables or the new class-based presets:

.nested-item {
  padding-left: var(--pt-level-padding-md);
  margin-bottom: var(--pt-level-gap-md);
}

/* Increase level for deeper nesting */
.nested-item.level-1 {
  --pt-level: 1;
}

.nested-item.level-2 {
  --pt-level: 2;
}
/* Or wrap with a level preset class */
/* available presets follow Levels.json modes, e.g., pantograph-tokens-level-default, ... */
<div class="pantograph-tokens pantograph-light pantograph-theme pantograph-tokens-level-default">
  <div class="nested-item">Item</div>
  <div class="nested-item level-1">Nested Item</div>
  <div class="nested-item level-2">Nested Deeper</div>
  <!-- you can override --pt-level per element or rely on preset variables -->
</div>

Typography Classes

Apply typography styles using CSS classes:

<!-- Title with title line heights -->
<h1 class="title">Main Title</h1>

<!-- Paragraph with paragraph line heights -->
<p class="paragraph">Body text content</p>

JavaScript/TypeScript

Import the token values directly in your JavaScript or TypeScript files:

import { 
  init, 
  getThemeInfo, 
  addCssToHead, 
  removeCssFromHead,
  getCoreHexColor,
  getCoreRgbColor 
} from '@pantograph/tokens';

// Initialize token system
init({
  element: '#app',
  dark: false,
  theme: 'pantograph',
  grayScale: 'neutral'
});

// Get theme information
const themeInfo = getThemeInfo({
  dark: true,
  theme: 'oktuple',
  grayScale: 'arsenic'
});
console.log(themeInfo.classes); // 'pantograph-tokens pantograph-dark oktuple-theme pantograph-arsenic'

// Manage CSS dynamically
addCssToHead('custom-styles', '.custom { color: red; }');
removeCssFromHead('custom-styles');

// Access color values
const primaryColor = getCoreHexColor('primary-5'); // '#0ea5e9'
const primaryRgb = getCoreRgbColor('primary-5'); // 'rgb(14, 165, 233)'

UnoCSS Integration

The tokens package provides a UnoCSS preset for seamless integration:

// uno.config.js
import { presetPantographVue } from '@pantograph/tokens'

export default {
  presets: [
    presetPantographVue()
  ]
}

Vue Integration

For Vue 3 applications, use the ConfigProvider component:

<template>
  <ConfigProvider :theme="themeConfig">
    <App />
  </ConfigProvider>
</template>

<script setup>
import { ConfigProvider } from '@pantograph/vue'
import { ref } from 'vue'

const themeConfig = ref({
  init: true,
  theme: 'pantograph',
  grayScale: 'neutral',
  dark: false,
  element: '#app'
})
</script>

Custom Theme Override

Override theme tokens for custom branding:

.custom-brand {
  /* Override primary colors */
  --pt-primary-0: var(--pt-pink-0);
  --pt-primary-1: var(--pt-pink-1);
  --pt-primary-2: var(--pt-pink-2);
  --pt-primary-3: var(--pt-pink-3);
  --pt-primary-4: var(--pt-pink-4);
  --pt-primary-5: var(--pt-pink-5);
  --pt-primary-6: var(--pt-pink-6);
  --pt-primary-7: var(--pt-pink-7);
  --pt-primary-8: var(--pt-pink-8);
  --pt-primary-9: var(--pt-pink-9);
  --pt-primary-oncolor: var(--pt-grayscale-light-0);
}

Package Structure

shared/tokens/
├── dist/                    # Built output
│   ├── index.js            # Main JavaScript export
│   ├── index.cjs           # CommonJS export
│   ├── index.d.ts          # TypeScript definitions
│   └── style/
│       └── index.css       # CSS custom properties
├── src/                    # Source code
│   ├── const/              # Token constants
│   ├── rules/              # UnoCSS rules
│   ├── style/              # Font files and CSS
│   └── utils/              # Utility functions
├── tokens/                 # JSON token definitions
│   ├── Colors.json         # Color tokens
│   ├── PrimitiveColors.json# Primitive color palette
│   ├── BrandColors.json    # Brand-specific colors
│   ├── GrayScale.json      # Grayscale colors
│   ├── Sizes.json          # Size and spacing tokens
│   ├── Typography.json     # Typography tokens
│   ├── Levels.json         # Indentation tokens
│   ├── Icon.json           # Icon tokens
│   └── generatedTokens.css # Generated CSS tokens
└── scripts/                # Build scripts

How It Works

Token Generation Process

• JSON Definitions: Token values are defined in JSON files in the tokens/ directory

• Build Process: The build system processes these JSON files and generates:

  • CSS custom properties with --pt-* prefix
  • Theme classes (.pantograph-light, .pantograph-dark, etc.)
  • Brand theme classes (.oktuple-theme, .claytap-theme, etc.)
  • Gray scale classes (.pantograph-arsenic, .pantograph-cool, etc.)
  • Language classes (.fa, .en)
  • Icon classes (.pc_icon--*)
  • Typography classes (.title, .paragraph)

• Final Output: The generatedTokens.css file contains all the mapped tokens with consistent --pt-* naming

Key Features

• Consistent Naming: All tokens use --pt-* prefix regardless of source
• Theme Switching: Colors change via CSS classes, not JavaScript
• RGB Values: Colors are stored as RGB values for rgba() usage
• Dynamic Theming: Multiple themes can coexist on the same page
• Language Support: Automatic font family switching based on language classes
• Level System: Dynamic indentation based on nesting depth

Contributing

Design tokens are generated from our Figma design system. Changes to token values should be made in Figma and then exported to this package using our internal tooling.

Development

To build the tokens package:

npm run build

This will generate the CSS custom properties and JavaScript exports from the JSON token definitions.

Token Updates

• Update token values in the JSON files in tokens/ directory
• Run npm run build to regenerate the CSS and JS exports
• Test the changes in the Vue component library
• Update documentation as needed

Important Notes

• All tokens are mapped to --pt-* prefix - no need to remember different prefixes
• Colors use RGB values - wrap with rgba() for opacity control
• Themes are applied via CSS classes - not JavaScript variables