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 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,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",