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>
134 lines
4.4 KiB
Markdown
134 lines
4.4 KiB
Markdown
# @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)
|
|
```
|