@the_awkward_customer/tokens-semantics

Semantic design tokens for the ELIZA Design System that provide meaningful context by referencing primitive tokens.

Overview

Semantic tokens create a layer of abstraction over primitive tokens, enabling theming and consistent naming across the design system. They output as CSS custom properties that reference primitive tokens using var().

New in v2.0.0: Typography utility classes for quick text styling.

Quick Start

npm install @the_awkward_customer/tokens-primitives@alpha
npm install @the_awkward_customer/tokens-semantics@alpha

@import '@the_awkward_customer/tokens-primitives';
@import '@the_awkward_customer/tokens-semantics';

.button {
  background-color: var(--background-brand-rest);
  color: var(--foreground-neutral-strong-inverted-rest);
  border: 1px solid var(--border-neutral-rest);
  padding: var(--space-8) var(--space-16);
  border-radius: var(--radii-8);
}

.button:hover {
  background-color: var(--background-brand-hover);
}

Installation

npm install @the_awkward_customer/tokens-semantics@alpha
npm install @the_awkward_customer/tokens-primitives@alpha

Note: Semantic tokens require primitives to be installed as they reference primitive token values.

Usage

Import Tokens

/* Import primitives first */
@import '@the_awkward_customer/tokens-primitives';

/* Then import semantics */
@import '@the_awkward_customer/tokens-semantics';

Import Specific Categories

@import '@the_awkward_customer/tokens-primitives/colors';
@import '@the_awkward_customer/tokens-semantics/tokens';

/* Typography utility classes */
@import '@the_awkward_customer/tokens-semantics/typography';

Typography Utility Classes

BEM-style utility classes for quick text styling:

<h1 class="text--heading-large">Page Title</h1>
<h2 class="text--heading-medium">Section Title</h2>
<p class="text--body-medium">Body text content</p>
<span class="text--eyebrows">CATEGORY</span>
<code class="text--code-small">const x = 1;</code>

Available Classes

Headings:

.text--heading-larger   /* 64px - Display headlines */
.text--heading-large    /* 40px - Page titles */
.text--heading-medium   /* 34px - Section titles */
.text--heading-small    /* 24px - Subsection titles */
.text--heading-smaller  /* 24px - Compact subsection titles */

Body Text:

.text--body-large    /* 16px - Large body text */
.text--body-medium   /* 14px - Default body text */
.text--body-small    /* 12px - Small body text */

Special:

.text--table      /* 11px - Table content */
.text--eyebrows   /* 9px - Labels, categories (uppercase) */

Code:

.text--code-small     /* 14px - Code blocks */
.text--code-smaller   /* 12px - Inline code */
.text--code-smallest  /* 11px - Compact code */

Class Structure

Each typography class includes:

• font-family - Primary or code font
• font-weight - Appropriate weight
• font-size - Size in rem
• line-height - Optimal leading
• letter-spacing - Tracking adjustments

.text--heading-large {
  font-family: var(--font-family-primary);
  font-weight: var(--font-weight-500);
  font-size: var(--font-size-40);
  line-height: var(--leading-36);
  letter-spacing: var(--tracking-300);
}

Available Tokens

Page (1 token)

--page-default: var(--colors-neutral-000);

Foreground (7 tokens)

Text and icon colors:

--foreground-neutral-weaker-rest: var(--colors-neutral-900);
--foreground-neutral-weak-rest: var(--colors-neutral-1000);
--foreground-neutral-rest: var(--colors-neutral-1100);
--foreground-neutral-strong-rest: var(--colors-neutral-1200);
--foreground-neutral-strong-inverted-rest: var(--colors-neutral-050);
--foreground-disabled: var(--colors-neutral-1100);

Background (17 tokens)

Component background colors with states:

Neutral backgrounds:

--background-neutral-weaker-rest: var(--colors-neutral-000);
--background-neutral-weak-rest: var(--colors-neutral-050);
--background-neutral-weak-hover: var(--colors-neutral-100);
--background-neutral-weak-active: var(--colors-neutral-200);

--background-neutral-rest: var(--colors-neutral-200);
--background-neutral-hover: var(--colors-neutral-300);
--background-neutral-active: var(--colors-neutral-400);

--background-neutral-strong-rest: var(--colors-neutral-300);
--background-neutral-strong-hover: var(--colors-neutral-400);
--background-neutral-strong-active: var(--colors-neutral-500);

Brand backgrounds:

--background-brand-rest: var(--colors-brand-500);
--background-brand-hover: var(--colors-brand-600);
--background-brand-active: var(--colors-brand-700);

Warning backgrounds:

--background-warning-weaker-rest: var(--colors-orange-300);
--background-warning-weaker-hover: var(--colors-orange-400);
--background-warning-weaker-active: var(--colors-orange-500);

--background-warning-rest: var(--colors-orange-500);
--background-warning-hover: var(--colors-orange-600);
--background-warning-active: var(--colors-orange-700);

Utility backgrounds:

--background-disabled: var(--colors-neutral-800);
--background-invisible: var(--colors-neutral-alpha-050-a0);

Border (7 tokens)

Border and outline colors:

--border-neutral-rest: var(--colors-neutral-400);
--border-neutral-hover: var(--colors-neutral-500);
--border-neutral-active: var(--colors-neutral-600);

--border-neutral-strong-rest: var(--colors-neutral-600);
--border-neutral-strong-hover: var(--colors-neutral-700);
--border-neutral-strong-active: var(--colors-neutral-800);

--border-disabled: var(--colors-neutral-800);

Overlay (1 token)

Modal and overlay backgrounds:

--overlay-neutral-rest: var(--colors-neutral-alpha-050-a40);

Spacing (semantic aliases)

--space-0: var(--size-size-00);
--space-1: var(--size-size-01);
--space-2: var(--size-size-02);
--space-4: var(--size-size-04);
--space-6: var(--size-size-06);
--space-8: var(--size-size-08);
--space-10: var(--size-size-10);
--space-12: var(--size-size-12);
--space-16: var(--size-size-16);
--space-20: var(--size-size-20);
--space-24: var(--size-size-24);
--space-32: var(--size-size-32);
--space-40: var(--size-size-40);
--space-48: var(--size-size-48);
--space-64: var(--size-size-64);

Radii (semantic aliases)

--radii-2: var(--radii-radius-02);
--radii-4: var(--radii-radius-04);
--radii-8: var(--radii-radius-08);
--radii-12: var(--radii-radius-12);
--radii-16: var(--radii-radius-16);
--radii-pill: var(--radii-radius-999);

Layout Sizes

Fixed layout widths in rem:

--sizes-layout-0: 0;
--sizes-layout-10: 5.5rem;    /* 88px */
--sizes-layout-20: 12rem;     /* 192px */
--sizes-layout-30: 18.5rem;   /* 296px */
--sizes-layout-40: 25rem;     /* 400px */
--sizes-layout-50: 31.5rem;   /* 504px */
--sizes-layout-60: 38rem;     /* 608px */
--sizes-layout-70: 44.5rem;   /* 712px */
--sizes-layout-80: 51rem;     /* 816px */
--sizes-layout-90: 57.5rem;   /* 920px */
--sizes-layout-100: 64rem;    /* 1024px */
--sizes-layout-110: 70.5rem;  /* 1128px */
--sizes-layout-120: 77rem;    /* 1232px */

Token Naming Convention

Format: --{element}-{variant}-{state}

• element: page, foreground, background, border, overlay, space, radii
• variant: neutral, neutral-weak, neutral-weaker, neutral-strong, brand, warning, warning-weaker, disabled, invisible
• state: rest, hover, active, inverted (optional)

State Naming

• rest - Default state
• hover - Mouse hover state
• active - Pressed/active state
• inverted - Inverted color (e.g., light text on dark background)

Variant Naming

• weaker - Lowest emphasis
• weak - Low emphasis
• (no modifier) - Standard emphasis
• strong - High emphasis

Breaking Changes in v2.0.0

1. Primitive token references updated - No longer use -dark suffix:
   • var(--colors-neutral-dark-000) → var(--colors-neutral-000)
2. New typography utility classes - BEM-style .text--* classes
3. New semantic scale tokens - spacing, radii, and layout aliases
4. File renamed: colors.css → tokens.css
   • Old: @import '@the_awkward_customer/tokens-semantics/colors';
   • New: @import '@the_awkward_customer/tokens-semantics/tokens';

Best Practices

Do: Use Semantic Tokens for Components

/* Good - Uses semantic tokens */
.button {
  background-color: var(--background-brand-rest);
  color: var(--foreground-neutral-strong-inverted-rest);
  padding: var(--space-8) var(--space-16);
  border-radius: var(--radii-8);
}

Don't: Use Primitive Tokens Directly in Components

/* Avoid - Uses primitives directly */
.button {
  background-color: var(--colors-brand-500);
  color: var(--colors-neutral-050);
  padding: var(--size-size-08) var(--size-size-16);
}

Do: Use Typography Utility Classes

<!-- Good - Uses utility class -->
<h1 class="text--heading-large">Title</h1>

<!-- Also good - Uses tokens directly when needed -->
<h1 style="font-size: var(--font-size-40); font-weight: var(--font-weight-500);">Title</h1>

Files

• dist/tokens.css - All semantic tokens (colors, spacing, radii, layout, typography composites)
• dist/typography-utilities.css - Typography utility classes (.text--*)
• dist/index.css - All semantic tokens combined

Dependencies

This package depends on @the_awkward_customer/tokens-primitives for token values.

License

UNLICENSED - Private package for internal use only.