blip-tokens 1.100.0 → 1.102.1
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 +252 -15
- package/build/icons.d.ts +19 -0
- package/build/icons.js +19 -0
- package/build/json/assets_icons.json +28 -18
- package/build/json/variables.json +11 -1
- package/build/scss/extended-color.scss +1 -1
- package/build/scss/theme-dark.scss +1 -1
- package/build/scss/theme-high-contrast.scss +1 -1
- package/build/scss/theme-light.scss +1 -1
- package/build/scss/variables.scss +1 -1
- package/package.json +2 -2
- package/properties/assets/icons.json +33 -3
package/README.md
CHANGED
|
@@ -1,26 +1,263 @@
|
|
|
1
1
|
# blip-tokens
|
|
2
|
-
|
|
2
|
+
|
|
3
|
+
Blip Design Tokens — the single source of truth for UI attributes (colors, spacing, typeface, icons, illustrations, etc.) consumed by the Blip Design System.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Table of Contents
|
|
8
|
+
|
|
9
|
+
- [Project Structure](#project-structure)
|
|
10
|
+
- [Design Tokens](#design-tokens)
|
|
11
|
+
- [Icons](#icons)
|
|
12
|
+
- [Adding New Icons](#adding-new-icons)
|
|
13
|
+
- [Icon Script (generate_icons)](#icon-script-generate_icons)
|
|
14
|
+
- [Icon TypeScript Types (generate_icon_types)](#icon-typescript-types-generate_icon_types)
|
|
15
|
+
- [Importing Icons in Your Project](#importing-icons-in-your-project)
|
|
16
|
+
- [Illustrations](#illustrations)
|
|
17
|
+
- [Emojis](#emojis)
|
|
18
|
+
- [Logos](#logos)
|
|
19
|
+
- [Build](#build)
|
|
20
|
+
- [Build Outputs](#build-outputs)
|
|
21
|
+
- [CI/CD](#cicd)
|
|
22
|
+
- [Contributing](#contributing)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
## Project Structure
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
blip-tokens/
|
|
29
|
+
├── assets/ # Raw SVG source files
|
|
30
|
+
│ ├── emojis/
|
|
31
|
+
│ ├── icons/
|
|
32
|
+
│ │ ├── outline/ # Outline-style icons (.svg)
|
|
33
|
+
│ │ └── solid/ # Solid-style icons (.svg)
|
|
34
|
+
│ │ └── flags/ # Flag icons (sub-folder)
|
|
35
|
+
│ ├── illustrations/ # Illustration categories (blip-outline, brand, default, …)
|
|
36
|
+
│ └── logos/
|
|
37
|
+
├── properties/ # Style Dictionary token source files
|
|
38
|
+
│ └── assets/
|
|
39
|
+
│ ├── icons.json # Icon registry (name → SVG path)
|
|
40
|
+
│ ├── emojis.json # Emoji registry
|
|
41
|
+
│ ├── illustrations.json # Illustration registry
|
|
42
|
+
│ ├── logos.json # Logo registry
|
|
43
|
+
│ ├── variables.json # Color palette tokens
|
|
44
|
+
│ ├── theme-light.json # Light theme semantic tokens
|
|
45
|
+
│ ├── theme-dark.json # Dark theme semantic tokens
|
|
46
|
+
│ ├── theme-high-contrast.json
|
|
47
|
+
│ └── extended-color.json # Extended color palette
|
|
48
|
+
├── scripts/
|
|
49
|
+
│ ├── generate_icons.cjs # Sync SVGs → icons.json registry
|
|
50
|
+
│ └── generate_icon_types.js # Generate TS types from filesystem
|
|
51
|
+
├── config.cjs # Style Dictionary configuration
|
|
52
|
+
├── build/ # Generated output (git-ignored)
|
|
53
|
+
├── docs/ # Architecture Decision Records
|
|
54
|
+
└── package.json
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Design Tokens
|
|
60
|
+
|
|
61
|
+
Token source files live in `properties/assets/`. Style Dictionary transforms them into multiple output formats during the build step.
|
|
62
|
+
|
|
63
|
+
| Source File | Description |
|
|
64
|
+
|---|---|
|
|
65
|
+
| `variables.json` | Base color palette (`primary-main`, `primary-dark`, …) |
|
|
66
|
+
| `theme-light.json` | Light theme semantic tokens (`brand`, `surface-1`, `content-default`, …) |
|
|
67
|
+
| `theme-dark.json` | Dark theme semantic tokens |
|
|
68
|
+
| `theme-high-contrast.json` | High contrast theme tokens |
|
|
69
|
+
| `extended-color.json` | Extended color set (`blue`, `ocean`, `green`, `yellow`, …) |
|
|
70
|
+
|
|
71
|
+
---
|
|
3
72
|
|
|
4
73
|
## Icons
|
|
5
|
-
Icons are generated in svg, and in this process we convert to base64 keeping them all within a single JSON file.
|
|
6
74
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
75
|
+
Icons are SVG files stored in `assets/icons/`. During the build, they are converted to **base64** and output as a single JSON file.
|
|
76
|
+
|
|
77
|
+
There are two icon variants:
|
|
78
|
+
|
|
79
|
+
| Variant | Directory | Naming convention in `icons.json` |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| **Outline** | `assets/icons/outline/` | `<name>-outline` |
|
|
82
|
+
| **Solid** | `assets/icons/solid/` | `<name>-solid` |
|
|
83
|
+
|
|
84
|
+
### Adding New Icons
|
|
85
|
+
|
|
86
|
+
1. **Place the SVG file** in the correct folder:
|
|
87
|
+
- Outline icons → `assets/icons/outline/`
|
|
88
|
+
- Solid icons → `assets/icons/solid/`
|
|
89
|
+
- (Sub-folders like `solid/flags/` are supported)
|
|
90
|
+
|
|
91
|
+
2. **Register the icon** in `properties/assets/icons.json`:
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
"icon-name-outline": {
|
|
95
|
+
"value": "assets/icons/outline/icon-name.svg"
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Or for solid:
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
"icon-name-solid": {
|
|
103
|
+
"value": "assets/icons/solid/icon-name.svg"
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
> The list is organized alphabetically, with all outline icons first, then all solid icons.
|
|
108
|
+
|
|
109
|
+
3. **Or use the automated script** (recommended):
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
cd scripts
|
|
113
|
+
node generate_icons.cjs
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
The script scans `assets/icons/`, detects unregistered SVGs, and interactively prompts you to add them to `icons.json`. It also sorts the file automatically.
|
|
117
|
+
|
|
118
|
+
4. **Build** to generate the base64 output and TypeScript types:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
npm run build
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Icon Script (`generate_icons`)
|
|
125
|
+
|
|
126
|
+
**File:** `scripts/generate_icons.cjs`
|
|
127
|
+
|
|
128
|
+
This CommonJS script:
|
|
129
|
+
- Recursively scans `assets/icons/` for `.svg` files
|
|
130
|
+
- Compares found files against `properties/assets/icons.json`
|
|
131
|
+
- Reports files that are missing from the registry or that reference missing SVGs
|
|
132
|
+
- Interactively asks whether to add unregistered files
|
|
133
|
+
- Auto-generates the key using the convention `<filename>-<variant>` (e.g. `add-outline`, `heart-solid`)
|
|
134
|
+
- Sorts the resulting JSON (outline first, then solid, both alphabetically)
|
|
135
|
+
|
|
136
|
+
### Icon TypeScript Types (`generate_icon_types`)
|
|
137
|
+
|
|
138
|
+
**File:** `scripts/generate_icon_types.js`
|
|
139
|
+
|
|
140
|
+
This ESM script runs automatically at the end of `npm run build`. It:
|
|
141
|
+
- Scans the filesystem (`assets/icons/outline/` and `assets/icons/solid/`) directly
|
|
142
|
+
- Generates `build/icons.js` with runtime arrays (`OutlineIcons`, `SolidIcons`, `AllIcons`) and helper functions (`isOutlineIcon`, `isSolidIcon`, `isValidIcon`)
|
|
143
|
+
- Generates `build/icons.d.ts` with TypeScript type definitions (`OutlineIcon`, `SolidIcon`, `IconName`)
|
|
144
|
+
|
|
145
|
+
### Importing Icons in Your Project
|
|
146
|
+
|
|
147
|
+
#### Runtime arrays
|
|
10
148
|
|
|
11
|
-
|
|
149
|
+
```typescript
|
|
150
|
+
import { OutlineIcons, SolidIcons, AllIcons } from 'blip-tokens/icons';
|
|
12
151
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
152
|
+
console.log(OutlineIcons); // ["123", "ab", "add", ...]
|
|
153
|
+
console.log(SolidIcons); // ["add", "attention", ...]
|
|
154
|
+
console.log(AllIcons); // Union of both, deduplicated
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
#### TypeScript types
|
|
17
158
|
|
|
18
|
-
|
|
159
|
+
```typescript
|
|
160
|
+
import type { OutlineIcon, SolidIcon, IconName } from 'blip-tokens/icons';
|
|
19
161
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
"value": "assets/icons/TYPE/NAME_ICON.svg"
|
|
162
|
+
function renderIcon(name: OutlineIcon) {
|
|
163
|
+
// TypeScript validates and auto-completes icon names
|
|
23
164
|
}
|
|
24
165
|
```
|
|
25
166
|
|
|
26
|
-
|
|
167
|
+
#### Helper functions
|
|
168
|
+
|
|
169
|
+
```typescript
|
|
170
|
+
import { isOutlineIcon, isSolidIcon, isValidIcon } from 'blip-tokens/icons';
|
|
171
|
+
|
|
172
|
+
if (isValidIcon(userInput)) {
|
|
173
|
+
// Safe to use
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
> See [AD-003](docs/ad/003-icon-type-exports.md) for full usage examples (React components, dynamic pickers, form validation).
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## Illustrations
|
|
182
|
+
|
|
183
|
+
Illustration SVGs live in `assets/illustrations/` organized by category (`default`, `brand`, `blip-outline`, `blip-solid`, `empty-states`, `screens`, `segmented`, `smartphone`, `spots`, `logo-integration`).
|
|
184
|
+
|
|
185
|
+
Registry: `properties/assets/illustrations.json`
|
|
186
|
+
|
|
187
|
+
During build, each category is output as a separate JSON file under `build/json/illustrations/<category>/`.
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## Emojis
|
|
192
|
+
|
|
193
|
+
Emoji SVGs live in `assets/emojis/`.
|
|
194
|
+
|
|
195
|
+
Registry: `properties/assets/emojis.json`
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Logos
|
|
200
|
+
|
|
201
|
+
Logo SVGs live in `assets/logos/`.
|
|
202
|
+
|
|
203
|
+
Registry: `properties/assets/logos.json`
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Build
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
npm run build
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
The build process runs two steps:
|
|
214
|
+
|
|
215
|
+
1. **Style Dictionary** (`config.cjs`) — transforms all token source files in `properties/` into build outputs
|
|
216
|
+
2. **Icon types generator** (`scripts/generate_icon_types.js`) — produces `build/icons.js` and `build/icons.d.ts`
|
|
217
|
+
|
|
218
|
+
### Build Outputs
|
|
219
|
+
|
|
220
|
+
```
|
|
221
|
+
build/
|
|
222
|
+
├── css/
|
|
223
|
+
│ └── classes.css # CSS utility classes (.color-*, .bg-*)
|
|
224
|
+
├── scss/
|
|
225
|
+
│ ├── variables.scss # Color palette as SCSS variables
|
|
226
|
+
│ ├── theme-light.scss
|
|
227
|
+
│ ├── theme-dark.scss
|
|
228
|
+
│ ├── theme-high-contrast.scss
|
|
229
|
+
│ └── extended-color.scss
|
|
230
|
+
├── json/
|
|
231
|
+
│ ├── variables.json # Flat JSON of all tokens
|
|
232
|
+
│ ├── assets_icons.json # Icons as base64
|
|
233
|
+
│ ├── assets_emojis.json # Emojis as base64
|
|
234
|
+
│ ├── assets_logos.json # Logos as base64
|
|
235
|
+
│ ├── colors.json
|
|
236
|
+
│ ├── theme-light.json
|
|
237
|
+
│ ├── theme-dark.json
|
|
238
|
+
│ ├── theme-high-contrast.json
|
|
239
|
+
│ ├── extended-color.json
|
|
240
|
+
│ └── illustrations/ # Per-category illustration JSONs
|
|
241
|
+
├── icons.js # Runtime icon arrays + helpers
|
|
242
|
+
├── icons.d.ts # TypeScript type definitions
|
|
243
|
+
└── index.js # Main entry point
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## CI/CD
|
|
249
|
+
|
|
250
|
+
- **Workflow:** `.github/workflows/nodejs.yml`
|
|
251
|
+
- **Trigger:** Push to `master`
|
|
252
|
+
- **Steps:** Checkout → Node 24 setup → `npm install` → `npm run build` → Semantic Release
|
|
253
|
+
- **Publish:** Automated via [Semantic Release](https://github.com/semantic-release/semantic-release) to npm
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Contributing
|
|
258
|
+
|
|
259
|
+
1. Follow [Conventional Commits](https://www.conventionalcommits.org/) — the release process depends on it
|
|
260
|
+
2. PR titles must use the correct type prefix (`feat:`, `fix:`, `chore:`, `docs:`, etc.)
|
|
261
|
+
3. When adding icons, prefer using the `generate_icons.cjs` script to keep `icons.json` consistent
|
|
262
|
+
4. Always run `npm run build` locally to verify your changes produce valid outputs
|
|
263
|
+
5. The `build/` directory is git-ignored — never commit it
|
package/build/icons.d.ts
CHANGED
|
@@ -162,8 +162,10 @@ export interface OutlineIconMap {
|
|
|
162
162
|
"file-txt-1": true;
|
|
163
163
|
"file-video-expired": true;
|
|
164
164
|
"filter": true;
|
|
165
|
+
"fire": true;
|
|
165
166
|
"folder": true;
|
|
166
167
|
"folder-add": true;
|
|
168
|
+
"folder-open": true;
|
|
167
169
|
"folder-save": true;
|
|
168
170
|
"gift": true;
|
|
169
171
|
"guide": true;
|
|
@@ -185,6 +187,7 @@ export interface OutlineIconMap {
|
|
|
185
187
|
"library": true;
|
|
186
188
|
"like": true;
|
|
187
189
|
"link": true;
|
|
190
|
+
"link-off": true;
|
|
188
191
|
"list": true;
|
|
189
192
|
"loading": true;
|
|
190
193
|
"localization": true;
|
|
@@ -297,6 +300,7 @@ export interface OutlineIconMap {
|
|
|
297
300
|
"true": true;
|
|
298
301
|
"typing": true;
|
|
299
302
|
"undo": true;
|
|
303
|
+
"unlink": true;
|
|
300
304
|
"unlock": true;
|
|
301
305
|
"unordered-list": true;
|
|
302
306
|
"unpin": true;
|
|
@@ -305,7 +309,12 @@ export interface OutlineIconMap {
|
|
|
305
309
|
"user-active": true;
|
|
306
310
|
"user-default": true;
|
|
307
311
|
"user-engaged": true;
|
|
312
|
+
"user-entry": true;
|
|
313
|
+
"user-exit": true;
|
|
308
314
|
"user-favorite": true;
|
|
315
|
+
"user-lock": true;
|
|
316
|
+
"user-sso": true;
|
|
317
|
+
"user-woman": true;
|
|
309
318
|
"verified": true;
|
|
310
319
|
"video": true;
|
|
311
320
|
"video-broken": true;
|
|
@@ -454,6 +463,7 @@ export interface SolidIconMap {
|
|
|
454
463
|
"finland-flag": true;
|
|
455
464
|
"folder": true;
|
|
456
465
|
"folder-add": true;
|
|
466
|
+
"folder-open": true;
|
|
457
467
|
"folder-save": true;
|
|
458
468
|
"france-flag": true;
|
|
459
469
|
"french-guyana-flag": true;
|
|
@@ -936,8 +946,10 @@ export interface IconMap {
|
|
|
936
946
|
"filter": true;
|
|
937
947
|
"filter-table": true;
|
|
938
948
|
"finland-flag": true;
|
|
949
|
+
"fire": true;
|
|
939
950
|
"folder": true;
|
|
940
951
|
"folder-add": true;
|
|
952
|
+
"folder-open": true;
|
|
941
953
|
"folder-save": true;
|
|
942
954
|
"france-flag": true;
|
|
943
955
|
"french-guyana-flag": true;
|
|
@@ -1013,6 +1025,7 @@ export interface IconMap {
|
|
|
1013
1025
|
"liechtenstein-flag": true;
|
|
1014
1026
|
"like": true;
|
|
1015
1027
|
"link": true;
|
|
1028
|
+
"link-off": true;
|
|
1016
1029
|
"list": true;
|
|
1017
1030
|
"lithuania-flag": true;
|
|
1018
1031
|
"loading": true;
|
|
@@ -1250,6 +1263,7 @@ export interface IconMap {
|
|
|
1250
1263
|
"united-kingdom-flag": true;
|
|
1251
1264
|
"united-nations-flag": true;
|
|
1252
1265
|
"united-states-flag": true;
|
|
1266
|
+
"unlink": true;
|
|
1253
1267
|
"unlock": true;
|
|
1254
1268
|
"unordered-list": true;
|
|
1255
1269
|
"unpin": true;
|
|
@@ -1259,7 +1273,12 @@ export interface IconMap {
|
|
|
1259
1273
|
"user-active": true;
|
|
1260
1274
|
"user-default": true;
|
|
1261
1275
|
"user-engaged": true;
|
|
1276
|
+
"user-entry": true;
|
|
1277
|
+
"user-exit": true;
|
|
1262
1278
|
"user-favorite": true;
|
|
1279
|
+
"user-lock": true;
|
|
1280
|
+
"user-sso": true;
|
|
1281
|
+
"user-woman": true;
|
|
1263
1282
|
"uzbekistn-flag": true;
|
|
1264
1283
|
"vanuatu-flag": true;
|
|
1265
1284
|
"variable": true;
|
package/build/icons.js
CHANGED
|
@@ -151,8 +151,10 @@ export const OutlineIcons = [
|
|
|
151
151
|
"file-txt-1",
|
|
152
152
|
"file-video-expired",
|
|
153
153
|
"filter",
|
|
154
|
+
"fire",
|
|
154
155
|
"folder",
|
|
155
156
|
"folder-add",
|
|
157
|
+
"folder-open",
|
|
156
158
|
"folder-save",
|
|
157
159
|
"gift",
|
|
158
160
|
"guide",
|
|
@@ -174,6 +176,7 @@ export const OutlineIcons = [
|
|
|
174
176
|
"library",
|
|
175
177
|
"like",
|
|
176
178
|
"link",
|
|
179
|
+
"link-off",
|
|
177
180
|
"list",
|
|
178
181
|
"loading",
|
|
179
182
|
"localization",
|
|
@@ -286,6 +289,7 @@ export const OutlineIcons = [
|
|
|
286
289
|
"true",
|
|
287
290
|
"typing",
|
|
288
291
|
"undo",
|
|
292
|
+
"unlink",
|
|
289
293
|
"unlock",
|
|
290
294
|
"unordered-list",
|
|
291
295
|
"unpin",
|
|
@@ -294,7 +298,12 @@ export const OutlineIcons = [
|
|
|
294
298
|
"user-active",
|
|
295
299
|
"user-default",
|
|
296
300
|
"user-engaged",
|
|
301
|
+
"user-entry",
|
|
302
|
+
"user-exit",
|
|
297
303
|
"user-favorite",
|
|
304
|
+
"user-lock",
|
|
305
|
+
"user-sso",
|
|
306
|
+
"user-woman",
|
|
298
307
|
"verified",
|
|
299
308
|
"video",
|
|
300
309
|
"video-broken",
|
|
@@ -446,6 +455,7 @@ export const SolidIcons = [
|
|
|
446
455
|
"finland-flag",
|
|
447
456
|
"folder",
|
|
448
457
|
"folder-add",
|
|
458
|
+
"folder-open",
|
|
449
459
|
"folder-save",
|
|
450
460
|
"france-flag",
|
|
451
461
|
"french-guyana-flag",
|
|
@@ -932,8 +942,10 @@ export const AllIcons = [
|
|
|
932
942
|
"filter",
|
|
933
943
|
"filter-table",
|
|
934
944
|
"finland-flag",
|
|
945
|
+
"fire",
|
|
935
946
|
"folder",
|
|
936
947
|
"folder-add",
|
|
948
|
+
"folder-open",
|
|
937
949
|
"folder-save",
|
|
938
950
|
"france-flag",
|
|
939
951
|
"french-guyana-flag",
|
|
@@ -1009,6 +1021,7 @@ export const AllIcons = [
|
|
|
1009
1021
|
"liechtenstein-flag",
|
|
1010
1022
|
"like",
|
|
1011
1023
|
"link",
|
|
1024
|
+
"link-off",
|
|
1012
1025
|
"list",
|
|
1013
1026
|
"lithuania-flag",
|
|
1014
1027
|
"loading",
|
|
@@ -1246,6 +1259,7 @@ export const AllIcons = [
|
|
|
1246
1259
|
"united-kingdom-flag",
|
|
1247
1260
|
"united-nations-flag",
|
|
1248
1261
|
"united-states-flag",
|
|
1262
|
+
"unlink",
|
|
1249
1263
|
"unlock",
|
|
1250
1264
|
"unordered-list",
|
|
1251
1265
|
"unpin",
|
|
@@ -1255,7 +1269,12 @@ export const AllIcons = [
|
|
|
1255
1269
|
"user-active",
|
|
1256
1270
|
"user-default",
|
|
1257
1271
|
"user-engaged",
|
|
1272
|
+
"user-entry",
|
|
1273
|
+
"user-exit",
|
|
1258
1274
|
"user-favorite",
|
|
1275
|
+
"user-lock",
|
|
1276
|
+
"user-sso",
|
|
1277
|
+
"user-woman",
|
|
1259
1278
|
"uzbekistn-flag",
|
|
1260
1279
|
"vanuatu-flag",
|
|
1261
1280
|
"variable",
|