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
commit 8a295c4acf
15 changed files with 2369 additions and 0 deletions
@@ -0,0 +1,133 @@
+# @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 <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:
+
+```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<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
+
+```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)
+```