Kaloyan Danchev
8a295c4acf
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>
@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 viapostMessageThemeTokens-- 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--ThemeTokenswith light mode defaultsdarkTheme--ThemeTokenswith dark mode defaultsAMPECO_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, setsdata-themeattribute 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)