Files

T

Kaloyan Danchev 8a295c4acf Initial commit: @ampeco/design-tokens v1.0.0

Design token system for AMPECO Embedded Web Apps with light/dark themes,
CSS custom properties, and runtime theme application via applyTheme().

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-18 19:34:08 +02:00

4.4 KiB

Raw Permalink Blame History

@ampeco/design-tokens

Design tokens for the AMPECO EWA (Embedded Web App). Provides theme definitions (light/dark), a token-to-CSS-variable mapping, and a runtime applyTheme() function that bridges the AMPECO mobile app design system to CSS custom properties.

Install

npm install @ampeco/design-tokens

Exports

Export path	What it provides
`@ampeco/design-tokens`	JS/TS: types, theme objects, `applyTheme()`, `mapAmpecoTokens()`, `TOKEN_CSS_MAP`
`@ampeco/design-tokens/css`	`css/variables.css` -- light-theme defaults plus spacing, radius, typography tokens

Usage

JavaScript / TypeScript

import { applyTheme, lightTheme, darkTheme, TOKEN_CSS_MAP } from '@ampeco/design-tokens';

// Apply light theme (sets CSS vars on <html>)
applyTheme('LIGHT');

// Apply dark theme with AMPECO mobile token overrides
applyTheme('DARK', {
  buttonsButtonPrimaryBackground: '#FF0000',
  surfaceSurfaceBackground: '#111111',
});

// Read a theme object directly
console.log(lightTheme.btnPrimaryBg); // '#00A573'
console.log(darkTheme.surfaceBg);     // '#000000'

// Look up the CSS variable name for a token
console.log(TOKEN_CSS_MAP.btnPrimaryBg); // '--btn-primary-bg'

CSS

Import the stylesheet to get light-theme defaults before JS initialises:

@import '@ampeco/design-tokens/css';

Then use the custom properties in your styles:

.button-primary {
  background: var(--btn-primary-bg);
  color: var(--btn-primary-text);
  font-size: var(--font-button-size);
  font-weight: var(--font-button-weight);
  line-height: var(--font-button-line-height);
  border-radius: var(--radius-m);
  padding: var(--spacing-s) var(--spacing-l);
}

Mapping AMPECO mobile tokens

The mobile app sends tokens using its own naming convention (e.g. buttonsButtonPrimaryBackground). Use mapAmpecoTokens() to convert them to EWA token keys:

import { mapAmpecoTokens } from '@ampeco/design-tokens';

const mobileTokens = {
  buttonsButtonPrimaryBackground: '#FF0000',
  textsTextBase: '#333333',
};

const ewaTokens = mapAmpecoTokens(mobileTokens);
// { btnPrimaryBg: '#FF0000', textBase: '#333333' }

API Reference

Types

AppTheme -- 'LIGHT' | 'DARK'
AmpecoDesignTokens -- Partial set of tokens as sent by the AMPECO mobile app via postMessage
ThemeTokens -- Complete set of EWA theme tokens (buttons, surfaces, text, feedback, input, separator, booking status)

Constants

TOKEN_CSS_MAP -- Record<keyof ThemeTokens, string> mapping each token key to its CSS custom property name (e.g. btnPrimaryBg -> '--btn-primary-bg')
lightTheme -- ThemeTokens with light mode defaults
darkTheme -- ThemeTokens with dark mode defaults
AMPECO_TO_EWA_MAP -- Record<string, keyof ThemeTokens> mapping AMPECO mobile token names to EWA token keys

Functions

applyTheme(theme: AppTheme, designTokens?: AmpecoDesignTokens): void -- Selects the base theme, merges AMPECO overrides, sets data-theme attribute on <html>, and writes all tokens as CSS custom properties on <html>.
mapAmpecoTokens(tokens: AmpecoDesignTokens): Partial<ThemeTokens> -- Converts AMPECO mobile token names to EWA token keys. Only truthy values are included.

CSS Variable Categories

The css/variables.css file defines variables beyond the themeable color tokens:

Category	Example variables	Notes
Spacing	`--spacing-xxxs` (2px) through `--spacing-xxxl` (64px)	9-step scale
Border radius	`--radius-s` (8px) through `--radius-xl` (32px)	4-step scale
Typography	`--font-h1-size`, `--font-body-medium-weight`, etc.	12 type styles
Component sizes	`--size-xs` (14px) through `--size-l` (44px)	4-step scale

Build

npm run build    # one-shot build via tsup (ESM + CJS + .d.ts)
npm run dev      # watch mode

Output lands in dist/ (ESM as index.js, CJS as index.cjs, types as index.d.ts and index.d.cts).

Source Files

src/
  index.ts          Public API barrel export
  types.ts          AppTheme, AmpecoDesignTokens
  tokens.ts         ThemeTokens interface, TOKEN_CSS_MAP
  light.ts          lightTheme defaults
  dark.ts           darkTheme defaults
  tokenMapping.ts   AMPECO_TO_EWA_MAP, mapAmpecoTokens()
  apply.ts          applyTheme()
css/
  variables.css     Static CSS custom properties (light defaults + layout tokens)

4.4 KiB Raw Permalink Blame History