@northslopetech/altitude-tokens

Design tokens for the Altitude design system, providing a consistent foundation for colors, typography, and spacing across all applications.

Structure

packages/altitude-tokens/
├── src/
│   ├── tokens/
│   │   ├── baseColors.ts          # Base color definitions
│   │   ├── semanticColors.ts      # Semantic color definitions
│   │   ├── typography.ts          # Typography definitions
│   │   └── tokens.ts              # Combined token definitions
│   └── index.ts                   # Package entry point
├── scripts/
│   └── build-tokens.js            # Build script
├── dist/                          # Generated token files
│   └── tokens.css                 # Base CSS custom properties
└── package.json                   # Package configuration

Installation

pnpm add @northslopetech/altitude-tokens

Note: If you're using @northslopetech/altitude-ui, this package is installed automatically as a transitive dependency — no need to install it explicitly.

Usage

This package publishes a single CSS file containing design token custom properties, the Tailwind v4 @theme registration, and semantic utility classes. Use it directly via @import in your stylesheet:

@import "@northslopetech/altitude-tokens";

Once imported, every token is available as a CSS custom property:

.my-component {
  background-color: var(--color-surface-default);
  color: var(--color-text-default);
  font: var(--typography-body-md);
}

Inside a Tailwind v4 build, the included @utility blocks add semantic class names (surface-default, interactive-accent, text-default, type-h1, etc.) that compose with Tailwind variants like hover:, dark:, and md:.

Fonts

The typography tokens reference Hanken Grotesk Variable and JetBrains Mono Variable by name, but this package does not bundle the font files. Loading the @font-face declarations is the responsibility of whatever layer renders text.

If you're using @northslopetech/altitude-ui, fonts are already handled — its styles.css @imports the matching @fontsource-variable packages automatically.

If you're using altitude-tokens standalone, install the fonts yourself:

pnpm add @fontsource-variable/hanken-grotesk @fontsource-variable/jetbrains-mono

@import "@fontsource-variable/hanken-grotesk";
@import "@fontsource-variable/jetbrains-mono";
@import "@northslopetech/altitude-tokens";

(Or load equivalents via Google Fonts, your own self-hosted woff2, next/font, etc. — the typography tokens just need a font family by that name to be available.)

Design Tokens

The TypeScript modules contain all design tokens organized by category:

Colors

• Base: white, black - fundamental colors
• Primitive families: stone, verdant, sky, amber, red with steps 50..950
• Semantic roles: grouped by bg, surface, interactive, text, border, focus, each with light/dark values

Typography

• Display: xs, sm, md, lg, xl - large heading styles
• Heading: sm, md, lg, xl - standard heading styles
• Body: xs, sm, md, lg, xl - body text styles
• Label: xs, sm, md, lg with regular/bold variants - UI label styles

Adding New Fonts

When adding new fonts to the design tokens:

1. Install the font in your application - The design system does not bundle fonts. Applications must install and make fonts available themselves
2. Add font definitions to typography tokens - Update the typography tokens to reference the new font family
3. Ensure font availability - Make sure the font is loaded and accessible in your application before using the tokens

Example font installation approaches:

• Package manager: Install font packages (e.g., pnpm install @fontsource/inter)
• Self-hosted: Include font files in your application's assets

The generated CSS will reference the font family, but the actual font files must be provided by the consuming application.

Generated Outputs

CSS Custom Properties

The build process generates CSS custom properties for each token set:

:root {
  --color-bg-default: #fafaf9;
  --color-surface-default: #ffffff;
  --color-text-default: #0c0a09;
  --typography-body-md: 400 16px/1.5 Hanken Grotesk;
}

.dark {
  --color-bg-default: #1c1917;
  --color-surface-default: #0c0a09;
  --color-text-default: #ffffff;
}

@theme {
  --color-stone-100: #f5f5f4;
  --color-verdant-400: #3ebd78;
}

Development

Build Commands

# Build tokens once
pnpm run build

# Watch for changes and rebuild
pnpm run dev

# Clean generated files
pnpm run clean

# Run tests
pnpm test

# Type checking
pnpm run check-types

Integration

The generated tokens are consumed by:

• @northslopetech/altitude-ui - Uses tokens for component styling
• Storybook - Displays token documentation
• Applications - Import the CSS file to get token custom properties