@cakemail-org/design-tokens

Design tokens for the Cakemail Design System. Provides colors, typography, spacing, and other design primitives in multiple formats.

Installation

npm install @cakemail-org/design-tokens
# or
pnpm add @cakemail-org/design-tokens
# or
yarn add @cakemail-org/design-tokens

Usage

CSS Custom Properties

@import '@cakemail-org/design-tokens/css';
@import '@cakemail-org/design-tokens/fonts.css';

.my-button {
  background-color: var(--color-brand-primary-teal);
  color: var(--color-semantic-text-primary);
  padding: var(--space-md) var(--space-lg);
  border-radius: var(--radius-medium);
  font-family: var(--font-primary);
  font-weight: var(--font-weight-semibold);
  box-shadow: var(--shadows-md);
}

.gradient-header {
  background: var(--gradients-brand);
  color: white;
}

.input-field {
  padding: var(--input-padding);
  font-size: var(--input-fontSize);
  border-radius: var(--input-borderRadius);
  border: var(--input-borderWidth) solid var(--input-borderColor-default);
}

.input-field:focus {
  border-color: var(--input-borderColor-focus);
  box-shadow: var(--shadows-focus);
}

JavaScript/TypeScript

import { colors, spacing, fontSize, shadows, gradients } from '@cakemail-org/design-tokens';

const styles = {
  color: colors['brand-primary-teal'],
  padding: `${spacing.md} ${spacing.lg}`,
  fontSize: fontSize.h1,
  boxShadow: shadows.md,
  background: gradients.brand,
};

SCSS Variables

@import '@cakemail-org/design-tokens/scss';

.my-button {
  background-color: $color-brand-primary-teal;
  padding: $space-md $space-lg;
  border-radius: $radius-medium;
}

Tailwind CSS (v4)

Cakemail targets Tailwind v4 (CSS-first). Wire the tokens in your main CSS entry — not via a JS preset:

@import "tailwindcss";
@import "@cakemail-org/design-tokens/theme.css";    /* tokens → @theme (self-contained: pulls in the CSS variables) */
@import "@cakemail-org/design-tokens/preset.css";   /* shadcn/ui bridge */

/* Tell Tailwind which files to scan for class names. WITHOUT this, utilities used
   only inside the prebuilt @cakemail-org components are silently stripped from your
   build (the classes never get generated). */
@source "./src";
@source "../node_modules/@cakemail-org/ui-app/dist";
@source "../node_modules/@cakemail-org/primitives/dist";

For dark-mode (.dark) and inverted surfaces, also add (before preset.css):

@import "@cakemail-org/design-tokens/css-dark";
@import "@cakemail-org/design-tokens/css-inverted";

Then use the standard themed Tailwind scale in your components:

<button className="bg-semantic-button-primary-bg text-white px-4 py-2 rounded-lg">
  Get Started
</button>

⚠️ Do NOT use @cakemail-org/design-tokens/tailwind (the JS preset.js) in v4. That is the v3 path, kept only for legacy v3 consumers. v4 consumers wire tokens through the CSS @imports above.

⚠️ Use the standard numeric scale (px-4, gap-3, rounded-lg) — not invented named spacing (px-lg, rounded-medium). The named spacing layer generates no CSS under Tailwind v4; the themed numeric scale is the system.

ℹ️ theme.css is self-contained — it pulls in the token CSS variables itself, so you do not add a separate @cakemail-org/design-tokens/css import alongside it.

Token Categories

Colors

• Brand: Primary purple, secondary teal, accent colors
• Neutral: 11-step shade system (50-1000)
• Tint: Light background colors
• Semantic: Text, background, button colors

Typography

• Font Families: Primary (Proxima Nova), Secondary (Aller)
• Font Sizes: h1-h4, body, small, eyebrow
• Font Weights: regular (400), medium (500), semibold (600)
• Line Heights: Matched to font sizes

Spacing

8px-based scale: xs (4px), sm (8px), md (16px), lg (24px), xl (32px), 2xl (48px), 3xl (64px), 4xl (96px), 5xl (128px)

Border Radius

• small (4px): Small elements, tags
• input (6px): Form inputs
• medium (8px): Buttons, cards
• large (12px): Cards, modals
• xlarge (16px): Testimonial cards
• 2xlarge (24px): Elevated components
• pill (100px): Pill-shaped buttons
• circle (50%): Circular elements

Shadows

• xs-2xl: Progressive elevation scale (6 levels)
• focus: Focus ring for interactive elements
• focus-error: Error state focus ring
• button-hover: Button hover elevation

Gradients

• brand: Primary purple → teal (135deg)
• brand-extended: Purple → teal → green (135deg)
• teal-purple: Horizontal teal → purple (90deg)
• accent-vibrant: Red → yellow → lime (135deg)
• overlay-fade: Transparent white fade (180deg)

Components

Button

• Default padding, fontSize, fontWeight, borderRadius
• Size variants: small, medium (default), large

Input

• Padding, fontSize, borderRadius, borderWidth
• Border colors: default, focus, error

Card

• Border radius, padding, shadow

Icon

• Size scale: xs (12px), sm (16px), md (20px), lg (24px), xl (32px), 2xl (48px)

Animation

Transition timing (300ms ease)

Z-Index

Layering scale for UI elements:

• dropdown (1000): Dropdown menus, popovers
• sticky (1020): Sticky positioned elements
• fixed (1030): Fixed positioned elements
• modalBackdrop (1040): Modal backdrop overlay
• modal (1050): Modal dialogs
• popover (1060): Popovers above modals
• tooltip (1070): Tooltips (highest layer)

Breakpoints

Responsive breakpoints:

• mobile (320px): Small mobile devices
• mobileLarge (480px): Large mobile devices
• tablet (768px): Tablets and small laptops
• desktop (1024px): Desktop screens
• desktopLarge (1280px): Large desktop screens
• desktopXLarge (1536px): Extra large desktop screens

Transitions

Timing functions for animations:

• fast (150ms ease): Quick transitions
• base (300ms ease): Default speed
• slow (500ms ease): Slower animations
• easeIn (300ms ease-in): Ease-in timing
• easeOut (300ms ease-out): Ease-out timing
• easeInOut (300ms ease-in-out): Ease-in-out timing

Fonts & Assets

Using Fonts

Import the fonts CSS to load Proxima Nova and Aller font families:

@import '@cakemail-org/design-tokens/fonts.css';

This provides:

• Proxima Nova: Light, Regular, Semibold, Bold, Extrabold, Black (with italic variants)
• Proxima Nova Condensed: Light, Regular, Semibold (with italic variants)
• Aller: Light, Regular, Bold (with italic variants) + Aller Display

Using Assets

Import logo and favicons:

import logo from '@cakemail-org/design-tokens/assets/logo';
import favicon from '@cakemail-org/design-tokens/assets/favicon';
import appleTouchIcon from '@cakemail-org/design-tokens/assets/apple-touch-icon';

See ASSETS.md for detailed asset usage guidelines.

Development

Build the tokens:

npm run build

Watch for changes:

npm run dev

Source

Tokens are defined in src/tokens.json and built into multiple formats using the build script.