@the_awkward_customer/tokens-primitives

v2.0.0-alpha.6

Published

2 months ago

BNY primitive design tokens

0High
0Medium
0Low

the_awkward_customer

design-tokens design-system css tokens primitives

@the_awkward_customer/tokens-primitives

Foundation design tokens for the ELIZA Design System with dark and light theme support.

Overview

Primitive tokens are the foundational design values that define colors, typography, spacing, and other visual properties. They output as CSS custom properties with concrete values:

Colors: OKLCH color space for perceptually uniform colors
Sizes: rem units (base 16px) for scalable layouts
Typography: rem-based font sizes and line heights

Quick Start

npm install @the_awkward_customer/tokens-primitives@alpha

@import '@the_awkward_customer/tokens-primitives';

.my-component {
  background-color: var(--colors-brand-500);
  color: var(--colors-neutral-1100);
  padding: var(--size-size-16);
  border-radius: var(--radii-radius-08);
  font-family: var(--font-family-primary);
  font-size: var(--font-size-14);
  line-height: var(--leading-20);
}

Installation

npm install @the_awkward_customer/tokens-primitives@alpha

Usage

Import All Tokens

@import '@the_awkward_customer/tokens-primitives';

Import Specific Categories

@import '@the_awkward_customer/tokens-primitives/colors';        /* Both dark & light themes */
@import '@the_awkward_customer/tokens-primitives/colors-dark';   /* Dark theme only */
@import '@the_awkward_customer/tokens-primitives/colors-light';  /* Light theme only */
@import '@the_awkward_customer/tokens-primitives/scale';         /* Spacing, radii, stroke */
@import '@the_awkward_customer/tokens-primitives/typography';    /* Fonts, sizes, leading, tracking */

Theme Support

Color tokens support both dark (default) and light themes:

<!-- Dark mode (default) -->
<html>
  <body>
    <div style="color: var(--colors-neutral-500)">Dark mode</div>
  </body>
</html>

<!-- Light mode -->
<html data-theme="light">
  <body>
    <div style="color: var(--colors-neutral-500)">Light mode</div>
  </body>
</html>

Available Tokens

Colors (OKLCH Format)

Colors use the OKLCH color space for perceptually uniform colors with better interpolation.

Color Palettes (theme-aware):

--colors-neutral-{000-1200} - Neutral colors (14 scales)
--colors-brand-{050-1200} - Brand colors (14 scales)
--colors-purple-{050-1200} - Purple accent colors (14 scales)
--colors-orange-{050-1200} - Orange/warning colors (14 scales)

Alpha Variants:

--colors-{palette}-alpha-{scale}-a{opacity} - Transparent variants

Examples:

/* Dark mode (default) */
[data-theme="dark"] {
  --colors-neutral-500: oklch(0.385 0.0505 239.2);
  --colors-brand-500: oklch(0.356 0.0612 225.5);
  --colors-brand-alpha-800-a50: oklch(0.574 0.0916 220.5 / 0.5);
}

/* Light mode */
[data-theme="light"] {
  --colors-neutral-500: oklch(0.455 0.0448 237.1);
  --colors-brand-500: oklch(0.424 0.0705 220.0);
}

Spacing (rem units)

Size scale from 0 to 128 in rem:

--size-size-00: 0;
--size-size-01: 0.0625rem;   /* 1px */
--size-size-02: 0.125rem;    /* 2px */
--size-size-04: 0.25rem;     /* 4px */
--size-size-06: 0.375rem;    /* 6px */
--size-size-08: 0.5rem;      /* 8px */
--size-size-10: 0.625rem;    /* 10px */
--size-size-12: 0.75rem;     /* 12px */
--size-size-16: 1rem;        /* 16px */
--size-size-20: 1.25rem;     /* 20px */
--size-size-24: 1.5rem;      /* 24px */
--size-size-28: 1.75rem;     /* 28px */
--size-size-32: 2rem;        /* 32px */
--size-size-36: 2.25rem;     /* 36px */
--size-size-40: 2.5rem;      /* 40px */
--size-size-48: 3rem;        /* 48px */
--size-size-64: 4rem;        /* 64px */
--size-size-80: 5rem;        /* 80px */
--size-size-96: 6rem;        /* 96px */
--size-size-128: 8rem;       /* 128px */

Border Radius (rem units)

--radii-radius-02: 0.125rem;    /* 2px */
--radii-radius-04: 0.25rem;     /* 4px */
--radii-radius-08: 0.5rem;      /* 8px */
--radii-radius-12: 0.75rem;     /* 12px */
--radii-radius-16: 1rem;        /* 16px */
--radii-radius-20: 1.25rem;     /* 20px */
--radii-radius-24: 1.5rem;      /* 24px */
--radii-radius-999: 62.4375rem; /* Pill shape */

Stroke Weight (unitless)

--stroke-weight-stroke-005: 0.5;
--stroke-weight-stroke-01: 1;
--stroke-weight-stroke-02: 2;

Typography

Font Families:

--font-family-primary: Inter;
--font-family-code: Geist Mono;

Font Weights:

--font-weight-400: Regular;
--font-weight-500: Medium;
--font-weight-600: SemiBold;
--font-weight-700: Bold;
--font-weight-800: ExtraBold;

Font Sizes (named by pixel value):

--font-size-9: 0.5625rem;    /* 9px */
--font-size-11: 0.6875rem;   /* 11px */
--font-size-12: 0.75rem;     /* 12px */
--font-size-14: 0.875rem;    /* 14px */
--font-size-16: 1rem;        /* 16px */
--font-size-18: 1.125rem;    /* 18px */
--font-size-20: 1.25rem;     /* 20px */
--font-size-24: 1.5rem;      /* 24px */
--font-size-28: 1.75rem;     /* 28px */
--font-size-34: 2.125rem;    /* 34px */
--font-size-40: 2.5rem;      /* 40px */
--font-size-48: 3rem;        /* 48px */
--font-size-64: 4rem;        /* 64px */

Line Height (Leading):

--leading-14: 0.875rem;   /* 14px */
--leading-16: 1rem;       /* 16px */
--leading-20: 1.25rem;    /* 20px */
--leading-24: 1.5rem;     /* 24px */
--leading-28: 1.75rem;    /* 28px */
--leading-32: 2rem;       /* 32px */
--leading-36: 2.25rem;    /* 36px */
--leading-40: 2.5rem;     /* 40px */
--leading-48: 3rem;       /* 48px */
--leading-60: 3.75rem;    /* 60px */
--leading-72: 4.5rem;     /* 72px */

Letter Spacing (Tracking):

--tracking-100: -0.075rem;    /* Tight */
--tracking-200: -0.0125rem;   /* Slightly tight */
--tracking-300: 0rem;         /* Normal */
--tracking-400: 0.0175rem;    /* Slightly loose */
--tracking-500: 0.03125rem;   /* Loose */

Token Naming Convention

Format: --{category}-{name}

category: colors, size, radii, stroke-weight, font-family, font-weight, font-size, leading, tracking
name: Descriptive name, often including the pixel value for sizing tokens

Examples:

--colors-brand-500 - Brand color at 500 scale
--size-size-16 - 16px size (1rem)
--font-size-14 - 14px font size (0.875rem)
--leading-20 - 20px line height (1.25rem)

Breaking Changes in v2.0.0

This version introduces breaking changes from v1.x:

Colors now use OKLCH format instead of hex/rgb
All numeric values are now in rem instead of raw numbers
Typography token names changed to use actual pixel values:
- --font-size-400 -> --font-size-14
- --leading-300 -> --leading-20
Font families updated: Inter and Geist Mono
No more calc() needed - values are already in rem units
File structure simplified:
- spacing.css, radius.css, stroke.css merged into scale.css
- New colors.css combines imports + :root defaults

Building from Source

Tokens are generated directly from Figma Variables API export:

npm run tokens:build

Files

dist/colors.css - All colors (imports dark + light, with :root defaults)
dist/colors-dark.css - Dark theme colors ([data-theme="dark"])
dist/colors-light.css - Light theme colors ([data-theme="light"])
dist/scale.css - Spacing, border radius, and stroke weight tokens
dist/typography.css - Typography tokens (fonts, sizes, leading, tracking)
dist/index.css - All tokens combined

License

UNLICENSED - Private package for internal use only.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@the_awkward_customer/tokens-primitives

Overview

Quick Start

Installation

Usage

Import All Tokens

Import Specific Categories

Theme Support

Available Tokens

Colors (OKLCH Format)

Spacing (rem units)

Border Radius (rem units)

Stroke Weight (unitless)

Typography

Token Naming Convention

Breaking Changes in v2.0.0

Building from Source

Files

License