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 CHANGED
@@ -1,26 +1,263 @@
1
1
  # blip-tokens
2
- Blip Design Tokens (BETA), refers to the attributes of the User Interface (UI) elements such as color, spacing, typeface, etc.
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
- ### How to insert some icon
8
- First you must place the icon inside assets/icons/outline || solid, this last depends on the icon you are going to use.
9
- .After that just go to properties/assets/icons.json and map.
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
- If you find it easier, you can use a script to insert all the files in icons.json. How to run this script:
149
+ ```typescript
150
+ import { OutlineIcons, SolidIcons, AllIcons } from 'blip-tokens/icons';
12
151
 
13
- First, go to folder 'scripts'
14
- `cd scripts`
15
- Then, run command:
16
- `node generate_icons.js`
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
- TYPE: outline / solid
159
+ ```typescript
160
+ import type { OutlineIcon, SolidIcon, IconName } from 'blip-tokens/icons';
19
161
 
20
- ```json
21
- "NAME_ICON-TYPE": {
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
- The list is organized by alphabetical order and type.
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",