@lemmo-lab/tokens 2.0.0 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +186 -57
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,82 +1,136 @@
|
|
|
1
1
|
# @lemmo-lab/tokens
|
|
2
2
|
|
|
3
|
-
> The
|
|
3
|
+
> **The Single Source of Truth Design Tokens Package for the Lemmo Ecosystem.**
|
|
4
|
+
> Authored in W3C DTCG format, strictly governed by 9 CI automated rules, and engineered for accessible multi-theme consumption.
|
|
5
|
+
|
|
6
|
+
[](https://www.npmjs.com/package/@lemmo-lab/tokens)
|
|
7
|
+
[](https://opensource.org/licenses/MIT)
|
|
8
|
+
[](#-ci-governance-rules)
|
|
9
|
+
[](#-accessibility--contrast-compliance-wcag-aa)
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 📑 Table of Contents
|
|
14
|
+
- [Architecture Overview](#-architecture-overview)
|
|
15
|
+
- [Shipped Themes (Tier 3)](#-shipped-themes-tier-3)
|
|
16
|
+
- [Installation & Quick Start](#-installation--quick-start)
|
|
17
|
+
- [Consuming Tokens](#-consuming-tokens)
|
|
18
|
+
- [1. CSS Custom Properties](#1-css-custom-properties)
|
|
19
|
+
- [2. Multi-Theme Switching](#2-multi-theme-switching)
|
|
20
|
+
- [3. Tailwind CSS Preset](#3-tailwind-css-preset)
|
|
21
|
+
- [4. JavaScript & TypeScript](#4-javascript--typescript)
|
|
22
|
+
- [CLI Tool (@lemmo-lab/tokens-cli)](#-cli-tool-lemmo-labtokens-cli)
|
|
23
|
+
- [Accessibility & Contrast Compliance (WCAG AA)](#-accessibility--contrast-compliance-wcag-aa)
|
|
24
|
+
- [Typography & Persian Script Protection](#-typography--persian-script-protection)
|
|
25
|
+
- [CI Governance Rules](#-ci-governance-rules)
|
|
26
|
+
- [Audit & Parity Guarantee](#-audit--parity-guarantee)
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 🌟 Architecture Overview
|
|
31
|
+
|
|
32
|
+
`@lemmo-lab/tokens` adheres strictly to the **Three-Tier Design Tokens Community Group (W3C DTCG)** model:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
packages/tokens/src/
|
|
36
|
+
├── core/ ← Tier 1: Raw Primitives (Palettes, 4px spacing ladder, radius, motion)
|
|
37
|
+
├── semantic/ ← Tier 2: Semantic Contract (--lemmo-surface-*, --lemmo-text-*, --lemmo-border-*)
|
|
38
|
+
└── themes/ ← Tier 3: Named Theme Presets (Mapping Tier 1 onto Tier 2 contracts)
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
1. **Tier 1 — Primitives (`core/`)**: Immutable foundation values. Color palettes (dark, light, neon, midnight, brand, status, alpha), spacing (4px rhythm from `0` to `2400`), typography scales, motion curves, and shadow definitions.
|
|
42
|
+
2. **Tier 2 — Semantic Contract (`semantic/`)**: Component-facing design tokens. Components never reference raw hex/px values directly; they reference semantic roles (`--lemmo-surface-primary`, `--lemmo-text-primary`, `--lemmo-border-subtle`).
|
|
43
|
+
3. **Tier 3 — Themes (`themes/`)**: Multi-theme presets that map raw primitives onto the semantic contract. Themes are strictly cosmetic and bounded; they may never override geometric properties like spacing or layout.
|
|
4
44
|
|
|
5
45
|
---
|
|
6
46
|
|
|
7
|
-
##
|
|
47
|
+
## 🎨 Shipped Themes (Tier 3)
|
|
8
48
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
49
|
+
`@lemmo-lab/tokens` ships with 4 production-ready, fully accessible theme presets:
|
|
50
|
+
|
|
51
|
+
| Theme Preset | Environment | Primary Canvas | Elevation / Cards | Key Accent | WCAG Contrast |
|
|
52
|
+
| :--- | :--- | :---: | :---: | :---: | :---: |
|
|
53
|
+
| **`default`** | Dark Mode (Default) | `#131517` | `#1c1e20` / `#23262a` | Lime `#d1fe17` | 14.02:1 (AAA) |
|
|
54
|
+
| **`light`** | Day / Light Mode | `#f8f9fa` | `#ffffff` / `#e9ecef` | LimeContrast `#386b00` | 6.42:1 (AA) |
|
|
55
|
+
| **`neon`** | Cyberpunk Contrast | `#08090a` | `#12151a` / `#181c24` | Electric Green `#00ff66` | 13.51:1 (AAA) |
|
|
56
|
+
| **`midnight`** | OLED Pure Black | `#000000` | `#0c0c0c` / `#161616` | Minimal White `#ffffff` | 21.00:1 (AAA) |
|
|
17
57
|
|
|
18
58
|
---
|
|
19
59
|
|
|
20
|
-
## 📦 Installation &
|
|
60
|
+
## 📦 Installation & Quick Start
|
|
21
61
|
|
|
22
62
|
```bash
|
|
23
|
-
|
|
24
|
-
# or
|
|
63
|
+
# Using npm
|
|
25
64
|
npm install @lemmo-lab/tokens
|
|
65
|
+
|
|
66
|
+
# Using pnpm
|
|
67
|
+
pnpm add @lemmo-lab/tokens
|
|
68
|
+
|
|
69
|
+
# Using yarn
|
|
70
|
+
yarn add @lemmo-lab/tokens
|
|
26
71
|
```
|
|
27
72
|
|
|
28
|
-
|
|
29
|
-
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 💻 Consuming Tokens
|
|
76
|
+
|
|
77
|
+
### 1. CSS Custom Properties
|
|
78
|
+
|
|
79
|
+
Import the base CSS bundle in your application's entry point (e.g. `index.css`, `App.css`, or `layout.tsx`):
|
|
30
80
|
|
|
31
81
|
```css
|
|
32
|
-
/* Loads
|
|
82
|
+
/* Loads base variables, typography, font resets, and default dark theme */
|
|
33
83
|
@import "@lemmo-lab/tokens/css/variables.css";
|
|
34
84
|
```
|
|
35
85
|
|
|
36
|
-
|
|
86
|
+
All variables use the official, standardized prefix:
|
|
87
|
+
```css
|
|
88
|
+
.card {
|
|
89
|
+
background-color: var(--lemmo-surface-primary);
|
|
90
|
+
color: var(--lemmo-text-primary);
|
|
91
|
+
border: 1px solid var(--lemmo-border-subtle);
|
|
92
|
+
border-radius: var(--lemmo-radius-card);
|
|
93
|
+
padding: var(--lemmo-space-400);
|
|
94
|
+
}
|
|
95
|
+
```
|
|
37
96
|
|
|
38
|
-
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
### 2. Multi-Theme Switching
|
|
100
|
+
|
|
101
|
+
To enable theme switching, import the modular theme stylesheets:
|
|
39
102
|
|
|
40
103
|
```css
|
|
41
|
-
/* Option A: Import
|
|
104
|
+
/* Option A: Import all themes bundled */
|
|
105
|
+
@import "@lemmo-lab/tokens/css/themes";
|
|
106
|
+
|
|
107
|
+
/* Option B: Import individual themes on demand */
|
|
42
108
|
@import "@lemmo-lab/tokens/css/themes/light.css";
|
|
43
109
|
@import "@lemmo-lab/tokens/css/themes/neon.css";
|
|
44
110
|
@import "@lemmo-lab/tokens/css/themes/midnight.css";
|
|
45
|
-
|
|
46
|
-
/* Option B: Import all themes at once */
|
|
47
|
-
@import "@lemmo-lab/tokens/css/themes";
|
|
48
111
|
```
|
|
49
112
|
|
|
50
|
-
|
|
113
|
+
Activate themes dynamically by setting `data-theme` on the root `<html>`, `<body>`, or any nested container:
|
|
51
114
|
|
|
52
115
|
```html
|
|
53
|
-
<!-- Default
|
|
54
|
-
<html
|
|
116
|
+
<!-- Default Dark Mode -->
|
|
117
|
+
<html>
|
|
55
118
|
|
|
56
|
-
<!-- Day / Light
|
|
57
|
-
<html
|
|
119
|
+
<!-- Day / Light Mode -->
|
|
120
|
+
<html data-theme="light">
|
|
58
121
|
|
|
59
|
-
<!-- Neon
|
|
60
|
-
<html
|
|
122
|
+
<!-- Neon Preset -->
|
|
123
|
+
<html data-theme="neon">
|
|
61
124
|
|
|
62
|
-
<!-- Midnight OLED
|
|
63
|
-
<html
|
|
125
|
+
<!-- Midnight OLED Preset -->
|
|
126
|
+
<html data-theme="midnight">
|
|
64
127
|
```
|
|
65
128
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
```typescript
|
|
69
|
-
import { tokens, themes } from '@lemmo-lab/tokens';
|
|
70
|
-
|
|
71
|
-
// Access themes
|
|
72
|
-
const darkTheme = themes.default;
|
|
73
|
-
const lightTheme = themes.light;
|
|
129
|
+
---
|
|
74
130
|
|
|
75
|
-
|
|
76
|
-
console.log(tokens.core.spacing[200]); // ".5rem"
|
|
77
|
-
```
|
|
131
|
+
### 3. Tailwind CSS Preset
|
|
78
132
|
|
|
79
|
-
|
|
133
|
+
`@lemmo-lab/tokens` includes a first-class Tailwind CSS preset compatible with Tailwind v3 and v4:
|
|
80
134
|
|
|
81
135
|
```javascript
|
|
82
136
|
// tailwind.config.js
|
|
@@ -84,34 +138,109 @@ import lemmoPreset from '@lemmo-lab/tokens/tailwind';
|
|
|
84
138
|
|
|
85
139
|
export default {
|
|
86
140
|
presets: [lemmoPreset],
|
|
87
|
-
|
|
141
|
+
content: [
|
|
142
|
+
'./src/**/*.{js,jsx,ts,tsx,vue,svelte,html}',
|
|
143
|
+
],
|
|
144
|
+
// Your customizations...
|
|
88
145
|
};
|
|
89
146
|
```
|
|
90
147
|
|
|
148
|
+
You can now use utility classes matching the design system:
|
|
149
|
+
```html
|
|
150
|
+
<div class="bg-[var(--lemmo-surface-primary)] text-[var(--lemmo-text-primary)] rounded-[var(--lemmo-radius-card)] p-4">
|
|
151
|
+
<button class="bg-[var(--lemmo-interactive-primary-background)] text-[var(--lemmo-interactive-primary-foreground)]">
|
|
152
|
+
Submit
|
|
153
|
+
</button>
|
|
154
|
+
</div>
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
### 4. JavaScript & TypeScript
|
|
160
|
+
|
|
161
|
+
Strongly typed token definitions for React, Vue, Svelte, or Node.js services:
|
|
162
|
+
|
|
163
|
+
```typescript
|
|
164
|
+
import { tokens, themes } from '@lemmo-lab/tokens';
|
|
165
|
+
|
|
166
|
+
// Access theme-specific semantic contracts
|
|
167
|
+
const currentTheme = themes.light;
|
|
168
|
+
console.log(currentTheme.color.surface.primary.background); // "#ffffff"
|
|
169
|
+
|
|
170
|
+
// Access primitive scale values
|
|
171
|
+
console.log(tokens.core.spacing[400]); // "1rem"
|
|
172
|
+
console.log(tokens.core.radius.base); // "0.5rem"
|
|
173
|
+
```
|
|
174
|
+
|
|
91
175
|
---
|
|
92
176
|
|
|
93
|
-
##
|
|
177
|
+
## 🛠️ CLI Tool (`@lemmo-lab/tokens-cli`)
|
|
94
178
|
|
|
95
|
-
|
|
96
|
-
2. **Mandatory Paired Tokens**: Every `*-background` token must have a paired `*-foreground` token.
|
|
97
|
-
3. **Relative Radius**: Only `--radius-base` may be set by themes; `--radius-control`, `--radius-card`, etc. are strictly derived via `calc()`.
|
|
98
|
-
4. **No Orphan Tokens**: Every semantic contract key must exist across all shipped themes.
|
|
99
|
-
5. **DTCG Standard**: All source tokens follow W3C DTCG format (`$type`, `$value`).
|
|
179
|
+
For projects that require standalone extraction, scaffolding, or theme inspection:
|
|
100
180
|
|
|
101
|
-
To validate all rules locally:
|
|
102
181
|
```bash
|
|
103
|
-
|
|
182
|
+
# Launch the interactive setup wizard
|
|
183
|
+
npx @lemmo-lab/tokens-cli install
|
|
184
|
+
|
|
185
|
+
# Install only the Light theme to a specific folder
|
|
186
|
+
npx @lemmo-lab/tokens-cli install --theme light --out ./src/styles/tokens
|
|
187
|
+
|
|
188
|
+
# Compare token differences between two themes
|
|
189
|
+
npx @lemmo-lab/tokens-cli diff default light
|
|
190
|
+
|
|
191
|
+
# Scaffold a new theme adhering to DTCG rules
|
|
192
|
+
npx @lemmo-lab/tokens-cli add-theme ocean
|
|
104
193
|
```
|
|
105
194
|
|
|
106
|
-
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## ♿ Accessibility & Contrast Compliance (WCAG AA)
|
|
198
|
+
|
|
199
|
+
- **Lime Light-Theme Contrast Fix**: Traditional brand lime (`#d1fe17`) drops to `1.28:1` on light backgrounds. To guarantee strict accessibility, `@lemmo-lab/tokens` introduces `color.brand.limeContrast` (`#386b00`), providing **6.42:1** contrast against white (`#ffffff`) and **6.09:1** against off-white (`#f8f9fa`), exceeding WCAG AA minimums.
|
|
200
|
+
- **Mandatory Token Pairing**: Every `*-background` token is guaranteed to ship with a paired `*-foreground` token verified to satisfy at least **4.5:1** contrast across all 4 themes.
|
|
201
|
+
- **Delta-E Discriminability (Delta-E >= 2.0)**: Eliminates imperceptible color duplicates (e.g. merging `#131416` into `#131517`).
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## 🔤 Typography & Persian Script Protection
|
|
206
|
+
|
|
207
|
+
- **Proportional Unitless Line-Heights**: All line-heights are defined as unitless ratios (`1.25`, `1.43`, etc.) ensuring proper scaling when font sizes change.
|
|
208
|
+
- **Persian Glyphic Integrity**: Negative letter-spacing breaks cursive Persian and Arabic connections (Nastaliq & Naskh). In `@lemmo-lab/tokens`, tracking is strictly reset to `letter-spacing: normal` under `:root[lang="fa"], [lang="fa"]`.
|
|
209
|
+
- **Decoupled Display Stack**: Hero font `Oddval` is isolated into `--lemmo-font-display`, preventing unintentional font fallbacks.
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## 🛡️ CI Governance Rules
|
|
214
|
+
|
|
215
|
+
Every token commit is validated automatically against 9 strict governance rules:
|
|
216
|
+
|
|
217
|
+
1. **Cosmetics vs. Geometry**: Themes may only override visual aesthetics (color, base radius, shadow, font, motion). Geometry (spacing, layout, width) is strictly forbidden in themes.
|
|
218
|
+
2. **Mandatory Paired Tokens**: Background tokens must have matching foreground tokens.
|
|
219
|
+
3. **Relative Radius Scale**: Radius scales must be derived from `--radius-base` via `calc()`.
|
|
220
|
+
4. **Zero Orphan Tokens**: All Tier 2 semantic keys must resolve in every shipped theme.
|
|
221
|
+
5. **W3C DTCG Compliance**: All source tokens require `$type` and `$value`.
|
|
222
|
+
6. **Minimum Contrast**: Paired foreground/background tokens must satisfy WCAG AA contrast (>= 4.5:1).
|
|
223
|
+
7. **Color Discriminability**: Adjacent palette steps must maintain Delta-E CIE76 >= 2.0.
|
|
224
|
+
8. **Zero Raw Hex in Gradients**: All 26 gradients must be 100% tokenized via `{...}` aliases per theme.
|
|
225
|
+
9. **Zero `lemu` Policy**: The legacy prefix `--lemu-*` is permanently eliminated in favor of `--lemmo-*`.
|
|
226
|
+
|
|
227
|
+
Run validator locally:
|
|
107
228
|
```bash
|
|
108
|
-
pnpm
|
|
229
|
+
pnpm validate
|
|
109
230
|
```
|
|
110
231
|
|
|
111
232
|
---
|
|
112
233
|
|
|
113
|
-
## 📊
|
|
234
|
+
## 📊 Audit & Parity Guarantee
|
|
235
|
+
|
|
236
|
+
`@lemmo-lab/tokens` is verified to be in **100% complete synchronization** with `System_design`. All 361 CSS variables, brand gradients, typography scales, and responsive breakpoints match with zero missing tokens and zero drift.
|
|
237
|
+
|
|
238
|
+
For technical deep-dives:
|
|
239
|
+
- [Audit & Parity Report](https://github.com/lemmo-lab/tokens/blob/main/docs/audit-system-design-sync.md)
|
|
240
|
+
- [Executive Architecture Decisions](https://github.com/lemmo-lab/tokens/blob/main/docs/EXECUTIVE-AUDIT-REPORT.md)
|
|
241
|
+
|
|
242
|
+
---
|
|
114
243
|
|
|
115
|
-
|
|
244
|
+
## 📄 License
|
|
116
245
|
|
|
117
|
-
|
|
246
|
+
MIT © [Lemmo Lab](https://github.com/lemmo-lab)
|