blip-tokens 1.101.0 → 1.103.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 +252 -15
- package/build/icons.d.ts +16 -0
- package/build/icons.js +16 -0
- package/build/json/assets_icons.json +20 -12
- package/build/json/variables.json +9 -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 +27 -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,6 +162,7 @@ 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;
|
|
167
168
|
"folder-open": true;
|
|
@@ -186,6 +187,7 @@ export interface OutlineIconMap {
|
|
|
186
187
|
"library": true;
|
|
187
188
|
"like": true;
|
|
188
189
|
"link": true;
|
|
190
|
+
"link-off": true;
|
|
189
191
|
"list": true;
|
|
190
192
|
"loading": true;
|
|
191
193
|
"localization": true;
|
|
@@ -298,6 +300,7 @@ export interface OutlineIconMap {
|
|
|
298
300
|
"true": true;
|
|
299
301
|
"typing": true;
|
|
300
302
|
"undo": true;
|
|
303
|
+
"unlink": true;
|
|
301
304
|
"unlock": true;
|
|
302
305
|
"unordered-list": true;
|
|
303
306
|
"unpin": true;
|
|
@@ -306,7 +309,12 @@ export interface OutlineIconMap {
|
|
|
306
309
|
"user-active": true;
|
|
307
310
|
"user-default": true;
|
|
308
311
|
"user-engaged": true;
|
|
312
|
+
"user-entry": true;
|
|
313
|
+
"user-exit": true;
|
|
309
314
|
"user-favorite": true;
|
|
315
|
+
"user-lock": true;
|
|
316
|
+
"user-sso": true;
|
|
317
|
+
"user-woman": true;
|
|
310
318
|
"verified": true;
|
|
311
319
|
"video": true;
|
|
312
320
|
"video-broken": true;
|
|
@@ -938,6 +946,7 @@ export interface IconMap {
|
|
|
938
946
|
"filter": true;
|
|
939
947
|
"filter-table": true;
|
|
940
948
|
"finland-flag": true;
|
|
949
|
+
"fire": true;
|
|
941
950
|
"folder": true;
|
|
942
951
|
"folder-add": true;
|
|
943
952
|
"folder-open": true;
|
|
@@ -1016,6 +1025,7 @@ export interface IconMap {
|
|
|
1016
1025
|
"liechtenstein-flag": true;
|
|
1017
1026
|
"like": true;
|
|
1018
1027
|
"link": true;
|
|
1028
|
+
"link-off": true;
|
|
1019
1029
|
"list": true;
|
|
1020
1030
|
"lithuania-flag": true;
|
|
1021
1031
|
"loading": true;
|
|
@@ -1253,6 +1263,7 @@ export interface IconMap {
|
|
|
1253
1263
|
"united-kingdom-flag": true;
|
|
1254
1264
|
"united-nations-flag": true;
|
|
1255
1265
|
"united-states-flag": true;
|
|
1266
|
+
"unlink": true;
|
|
1256
1267
|
"unlock": true;
|
|
1257
1268
|
"unordered-list": true;
|
|
1258
1269
|
"unpin": true;
|
|
@@ -1262,7 +1273,12 @@ export interface IconMap {
|
|
|
1262
1273
|
"user-active": true;
|
|
1263
1274
|
"user-default": true;
|
|
1264
1275
|
"user-engaged": true;
|
|
1276
|
+
"user-entry": true;
|
|
1277
|
+
"user-exit": true;
|
|
1265
1278
|
"user-favorite": true;
|
|
1279
|
+
"user-lock": true;
|
|
1280
|
+
"user-sso": true;
|
|
1281
|
+
"user-woman": true;
|
|
1266
1282
|
"uzbekistn-flag": true;
|
|
1267
1283
|
"vanuatu-flag": true;
|
|
1268
1284
|
"variable": true;
|
package/build/icons.js
CHANGED
|
@@ -151,6 +151,7 @@ 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",
|
|
156
157
|
"folder-open",
|
|
@@ -175,6 +176,7 @@ export const OutlineIcons = [
|
|
|
175
176
|
"library",
|
|
176
177
|
"like",
|
|
177
178
|
"link",
|
|
179
|
+
"link-off",
|
|
178
180
|
"list",
|
|
179
181
|
"loading",
|
|
180
182
|
"localization",
|
|
@@ -287,6 +289,7 @@ export const OutlineIcons = [
|
|
|
287
289
|
"true",
|
|
288
290
|
"typing",
|
|
289
291
|
"undo",
|
|
292
|
+
"unlink",
|
|
290
293
|
"unlock",
|
|
291
294
|
"unordered-list",
|
|
292
295
|
"unpin",
|
|
@@ -295,7 +298,12 @@ export const OutlineIcons = [
|
|
|
295
298
|
"user-active",
|
|
296
299
|
"user-default",
|
|
297
300
|
"user-engaged",
|
|
301
|
+
"user-entry",
|
|
302
|
+
"user-exit",
|
|
298
303
|
"user-favorite",
|
|
304
|
+
"user-lock",
|
|
305
|
+
"user-sso",
|
|
306
|
+
"user-woman",
|
|
299
307
|
"verified",
|
|
300
308
|
"video",
|
|
301
309
|
"video-broken",
|
|
@@ -934,6 +942,7 @@ export const AllIcons = [
|
|
|
934
942
|
"filter",
|
|
935
943
|
"filter-table",
|
|
936
944
|
"finland-flag",
|
|
945
|
+
"fire",
|
|
937
946
|
"folder",
|
|
938
947
|
"folder-add",
|
|
939
948
|
"folder-open",
|
|
@@ -1012,6 +1021,7 @@ export const AllIcons = [
|
|
|
1012
1021
|
"liechtenstein-flag",
|
|
1013
1022
|
"like",
|
|
1014
1023
|
"link",
|
|
1024
|
+
"link-off",
|
|
1015
1025
|
"list",
|
|
1016
1026
|
"lithuania-flag",
|
|
1017
1027
|
"loading",
|
|
@@ -1249,6 +1259,7 @@ export const AllIcons = [
|
|
|
1249
1259
|
"united-kingdom-flag",
|
|
1250
1260
|
"united-nations-flag",
|
|
1251
1261
|
"united-states-flag",
|
|
1262
|
+
"unlink",
|
|
1252
1263
|
"unlock",
|
|
1253
1264
|
"unordered-list",
|
|
1254
1265
|
"unpin",
|
|
@@ -1258,7 +1269,12 @@ export const AllIcons = [
|
|
|
1258
1269
|
"user-active",
|
|
1259
1270
|
"user-default",
|
|
1260
1271
|
"user-engaged",
|
|
1272
|
+
"user-entry",
|
|
1273
|
+
"user-exit",
|
|
1261
1274
|
"user-favorite",
|
|
1275
|
+
"user-lock",
|
|
1276
|
+
"user-sso",
|
|
1277
|
+
"user-woman",
|
|
1262
1278
|
"uzbekistn-flag",
|
|
1263
1279
|
"vanuatu-flag",
|
|
1264
1280
|
"variable",
|