# @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 ```bash 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 ```ts import { applyTheme, lightTheme, darkTheme, TOKEN_CSS_MAP } from '@ampeco/design-tokens'; // Apply light theme (sets CSS vars on ) 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: ```css @import '@ampeco/design-tokens/css'; ``` Then use the custom properties in your styles: ```css .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: ```ts 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` 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` 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 ``, and writes all tokens as CSS custom properties on ``. - **`mapAmpecoTokens(tokens: AmpecoDesignTokens): Partial`** -- 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 ```bash 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) ```