blip-tokens 2.0.2 → 2.2.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
@@ -9,6 +9,7 @@ Blip Design Tokens — the single source of truth for UI attributes (colors, spa
9
9
  - [Getting Started](#getting-started)
10
10
  - [Project Structure](#project-structure)
11
11
  - [Design Tokens](#design-tokens)
12
+ - [Figma Tokens and Themes](#figma-tokens-and-themes)
12
13
  - [Icons](#icons)
13
14
  - [Adding New Icons](#adding-new-icons)
14
15
  - [Icon Script (generate_icons)](#icon-script-generate_icons)
@@ -52,25 +53,33 @@ blip-tokens/
52
53
  │ │ └── flags/ # Flag icons (sub-folder)
53
54
  │ ├── illustrations/ # Illustration categories (blip-outline, brand, default, …)
54
55
  │ └── logos/
55
- ├── properties/ # Style Dictionary token source files
56
+ ├── properties/ # Asset registries and legacy token sources (published)
56
57
  │ └── assets/
57
58
  │ ├── icons.json # Icon registry (name → SVG path)
58
59
  │ ├── emojis.json # Emoji registry
59
60
  │ ├── illustrations.json # Illustration registry
60
61
  │ ├── logos.json # Logo registry
61
62
  │ ├── components.json # Component artwork registry
62
- │ ├── variables.json # Color palette tokens
63
- │ ├── theme-light.json # Light theme semantic tokens
64
- │ ├── theme-dark.json # Dark theme semantic tokens
63
+ │ ├── variables.json # Legacy color palette tokens
64
+ │ ├── theme-light.json # Legacy light theme semantic tokens
65
+ │ ├── theme-dark.json # Legacy dark theme semantic tokens
65
66
  │ ├── theme-high-contrast.json
66
67
  │ └── extended-color.json # Extended color palette
68
+ ├── figma-source/ # Reviewed live Figma snapshot and sync audit
67
69
  ├── scripts/
70
+ │ ├── build_tokens.js # Figma-derived --uai-* outputs (Style Dictionary 5)
71
+ │ ├── figma-tokens.js # Variable snapshot validation and compilation
72
+ │ ├── figma-styles.js # Effect and text style compilation
73
+ │ ├── collect_tokens.js # Assemble exported Figma chunks
74
+ │ ├── sync_tokens.js # Preview/apply variable syncs
75
+ │ ├── sync_styles.js # Preview/apply style syncs
68
76
  │ ├── generate_icons.cjs # Sync SVGs → icons.json registry
69
77
  │ ├── generate_icon_types.js # Generate TS types from filesystem
70
78
  │ ├── generate_assets.cjs # Validate/copy CDN SVGs and write manifest
71
79
  │ ├── release_assets.cjs # Build/upload exact Semantic Release version
72
80
  │ └── test/ # Asset build and release regression tests
73
- ├── config.cjs # Style Dictionary configuration
81
+ ├── tests/ # Figma token pipeline, theme cascade and package tests
82
+ ├── config.cjs # Build entry: legacy tokens (Style Dictionary 2), icons, Figma tokens, CDN assets
74
83
  ├── build/ # Generated output (git-ignored)
75
84
  ├── docs/ # Architecture Decision Records
76
85
  └── package.json
@@ -80,15 +89,421 @@ blip-tokens/
80
89
 
81
90
  ## Design Tokens
82
91
 
83
- Token source files live in `properties/assets/`. Style Dictionary transforms them into multiple output formats during the build step.
92
+ The package publishes two token sets side by side while components migrate:
93
+
94
+ | Set | Source | Names | Status |
95
+ |---|---|---|---|
96
+ | **Figma tokens** | Figma variable library, `figma-source/` | `--uai-*` | Canonical; use for new work |
97
+ | **Legacy tokens** | `properties/assets/*.json` | `.color-*` / `.bg-*` classes, `$` SCSS variables, flat JSON | Unchanged; kept until blip-ds has migrated |
98
+
99
+ Legacy sources:
84
100
 
85
101
  | Source File | Description |
86
102
  |---|---|
87
- | `variables.json` | Base color palette (`primary-main`, `primary-dark`, …) |
88
- | `theme-light.json` | Light theme semantic tokens (`brand`, `surface-1`, `content-default`, …) |
89
- | `theme-dark.json` | Dark theme semantic tokens |
90
- | `theme-high-contrast.json` | High contrast theme tokens |
91
- | `extended-color.json` | Extended color set (`blue`, `ocean`, `green`, `yellow`, …) |
103
+ | `variables.json` | Legacy base color palette |
104
+ | `theme-light.json` | Legacy light theme |
105
+ | `theme-dark.json` | Legacy dark theme |
106
+ | `theme-high-contrast.json` | Legacy high-contrast theme |
107
+ | `extended-color.json` | Legacy extended color set |
108
+
109
+ Legacy outputs (`build/json/*`, `build/scss/*`, `build/css/classes.css`) are
110
+ generated by the unchanged Style Dictionary 2 build, into the same folders as the
111
+ new `uai-*` files. The Figma pipeline only adds `uai-*` files, so migrating
112
+ components can rely on the legacy files until the legacy set is retired.
113
+
114
+ ## Figma Tokens and Themes
115
+
116
+ The architecture and publication policy are recorded in
117
+ [AD-004](docs/ad/004-figma-token-pipeline-and-publication.md) and
118
+ [AD-005](docs/ad/005-legacy-and-figma-token-coexistence.md).
119
+
120
+ The package name remains **`blip-tokens`**, published to the public npm registry.
121
+ The reviewed source is the
122
+ [Figma variable library](https://www.figma.com/design/xNgjSCmKfbgd3ed5mIPdHo/UAI-Design-Tokens).
123
+ Builds run offline from `figma-source/variables.json` and
124
+ `figma-source/styles.json`; they never fetch Figma or require Figma credentials.
125
+
126
+ The internal snapshot preserves collection and variable IDs, descriptions,
127
+ scopes, modes and raw values/aliases. Foundation is internal build input and is
128
+ **not included in the Figma token outputs**. Its values are resolved into the
129
+ semantic tokens that use them. Only three semantic collections are published.
130
+ Public names are `--uai-` followed by the token path **without** the collection
131
+ name:
132
+
133
+ | Figma collection | Figma name | Example CSS custom property |
134
+ |---|---|---|
135
+ | Typography | `body/base/font-size` | `--uai-body-base-font-size` |
136
+ | Colors | `surface/background` | `--uai-surface-background` |
137
+ | Dimensions | `spacing/md` | `--uai-spacing-md` |
138
+ | Effect styles | `elevation/1` | `--uai-elevation-1` |
139
+
140
+ Names must be unique across the three published collections; the build fails on
141
+ a collision instead of overwriting a token. Text styles are not published as
142
+ CSS classes; see [Typography](#typography).
143
+
144
+ The raw Figma snapshot, including Foundation, is excluded from the published
145
+ package. Generated DTCG JSON contains only semantic tokens, with primitive
146
+ references resolved to values so it has no dangling aliases. Descriptions,
147
+ Figma scopes and variable IDs stay attached to each published semantic token.
148
+ CSS custom properties include each token's Figma usage description as a
149
+ comment. The legacy outputs remain available alongside them.
150
+ The 305-variable count covers variable collections only: 206 Foundation
151
+ primitives are internal, and 99 semantic variables are published. Separately,
152
+ the Figma file has eight elevation effect styles, published as variables, and
153
+ 28 text styles, published as metadata, without exposing Foundation primitives.
154
+ There are no per-component color or typography tokens: components use the
155
+ semantic tokens directly, so their names stay stable across light and dark modes.
156
+
157
+ ### Using the tokens in a component
158
+
159
+ The tokens are an internal contract of the blip-ds design system. Only blip-ds
160
+ components read them. Micro frontends (MFEs) consume blip-ds components and do
161
+ not import `blip-tokens` or use `var(--uai-*)`: spacing and layout come from the
162
+ design system's grids and templates, which use the tokens internally. If an MFE
163
+ needs something the design system does not cover, the design system changes.
164
+
165
+ blip-ds loads the tokens once, in its own entry:
166
+
167
+ ```js
168
+ import 'blip-tokens/css/colors';
169
+ import 'blip-tokens/css/typography';
170
+ import 'blip-tokens/css/dimensions';
171
+ import 'blip-tokens/css/shadows';
172
+ // or, for all four: import 'blip-tokens/css';
173
+ ```
174
+
175
+ Components then read the variables in their own styles. There is nothing to
176
+ import per component. For example, a button:
177
+
178
+ ```scss
179
+ .button {
180
+ height: var(--uai-sizing-2xl);
181
+ padding: 0 var(--uai-spacing-md);
182
+ border-radius: var(--uai-radius-md);
183
+ border: var(--uai-border-width-default) solid transparent;
184
+ font-family: var(--uai-font-family-sans);
185
+ font-size: var(--uai-body-base-font-size);
186
+ line-height: var(--uai-body-base-line-height);
187
+ font-weight: var(--uai-font-weight-semibold);
188
+
189
+ &--primary {
190
+ background: var(--uai-action-primary-default);
191
+ color: var(--uai-action-primary-foreground);
192
+ &:hover { background: var(--uai-action-primary-hover); }
193
+ &:active { background: var(--uai-action-primary-pressed); }
194
+ }
195
+
196
+ &:focus-visible {
197
+ outline: var(--uai-border-width-thick) solid var(--uai-border-ring);
198
+ }
199
+ }
200
+ ```
201
+
202
+ The Figma code syntax of every semantic variable shows its CSS name, for example
203
+ `var(--uai-action-primary-default)`, so names can be copied from the design.
204
+ Foundation primitives have no code syntax because they are not published.
205
+ Use the CSS variables for styling. The SCSS variables (`$uai-*`) and the
206
+ JavaScript maps hold static values and do not follow the theme.
207
+
208
+ The output is split by what the tokens are. Only colors depend on the theme:
209
+
210
+ | Entry | File | Tokens | Declared on |
211
+ |---|---|---|---|
212
+ | `blip-tokens/css` | `build/css/uai.css` | Imports the four files below | — |
213
+ | `blip-tokens/css/colors` | `build/css/uai-colors.css` | Surface, content, action, border, feedback, overlay and fixed colors | Every theme root (light and dark) |
214
+ | `blip-tokens/css/typography` | `build/css/uai-typography.css` | Font families, sizes and line heights per role, weights, letter spacing | The outermost theme root |
215
+ | `blip-tokens/css/dimensions` | `build/css/uai-dimensions.css` | Spacing, sizing, radius, border width | The outermost theme root |
216
+ | `blip-tokens/css/shadows` | `build/css/uai-shadows.css` | Eight elevation shadows | The outermost theme root |
217
+
218
+ SCSS follows the same split: `blip-tokens/scss/colors-light`,
219
+ `scss/colors-dark`, `scss/typography`, `scss/dimensions` and `scss/shadows`.
220
+
221
+ The tokens are never declared at `:root`, `html` or `body`, so loading the CSS
222
+ does not change anything outside the theme roots. The `--uai-` prefix also keeps
223
+ every name apart from the v1 tokens, so v1 and v2 components can share a page.
224
+ Components never redeclare the variables; they only read them. Only elements
225
+ inside a theme root have tokens, so a component outside one renders without them.
226
+
227
+ A container can override a token for everything inside it, including nested
228
+ theme regions:
229
+
230
+ ```css
231
+ .compact-panel { --uai-spacing-md: 0.75rem; }
232
+ ```
233
+
234
+ ### Themes
235
+
236
+ A theme root is an element with `data-uai-theme="light"` or `"dark"`. The
237
+ blip-ds theme provider renders that attribute on its host, and everything
238
+ inside the provider inherits the tokens. The nearest root wins for colors, so
239
+ regions can be nested:
240
+
241
+ ```html
242
+ <bds-theme-provider theme="dark" data-uai-theme="dark">
243
+ …
244
+ <aside data-uai-theme="light">…</aside> <!-- light region inside it -->
245
+ </bds-theme-provider>
246
+ ```
247
+
248
+ The provider is the same `bds-theme-provider` used today, extended for v2: it
249
+ keeps the v1 `theme--*` classes and `--color-*` variables for the v1 components,
250
+ and also renders `data-uai-theme` for the new ones. The v1 classes and variables
251
+ do not feed the new tokens.
252
+
253
+ Each theme root also sets the CSS `color-scheme`. Typography, dimensions and
254
+ shadows do not depend on the theme, so they are declared only on the outermost
255
+ root and inherited by nested regions; that is why an override on a container
256
+ reaches components inside a nested region. The selectors use `:where()`, so a
257
+ rule that overrides a token on the theme root itself always wins.
258
+
259
+ The provider must:
260
+
261
+ - render `data-uai-theme` on its host, at the mount point of each MFE, in the
262
+ light DOM: a stylesheet loaded in the document does not reach elements inside
263
+ another component's shadow root;
264
+ - emit only `light` or `dark`. Any other value, including an empty one, makes the
265
+ element a theme root without colors. The v1 `high-contrast` theme has no Figma
266
+ equivalent, so the provider maps it to `light` or `dark`;
267
+ - copy the nearest `data-uai-theme` to the containers of portals (modals,
268
+ tooltips, dropdowns), which attach to `<body>` and sit outside the provider;
269
+ - warn in development when a v2 component has no theme root above it.
270
+
271
+ The package does not read OS preferences or persist the selection. Both themes
272
+ expose the same custom-property names.
273
+
274
+ ### Versioning of the tokens
275
+
276
+ Several versions of blip-ds v2 can end up on one page, each with its own copy of
277
+ the token CSS, and the same selectors then compete. To keep that safe, within a
278
+ major version tokens are only added or have their values adjusted, and are never
279
+ renamed or removed. Renames and removals ship in a major release.
280
+
281
+ ### Trying the tokens before a release
282
+
283
+ `build/` is generated and not committed, so a pull request shows the pipeline
284
+ and the Figma snapshots, not the CSS. To see the files:
285
+
286
+ - run `npm ci && npm run build` on the branch and open `build/css/`; or
287
+ - download the `build-artifacts` artifact from the pull request's CI run; or
288
+ - run `npm run build && npm pack` on the branch and install the `.tgz` in blip-ds with
289
+ `npm install ../blip-tokens/blip-tokens-0.0.0-development.tgz`.
290
+
291
+ ### Shadows
292
+
293
+ The default CSS entry also includes the eight Figma elevation styles as custom
294
+ properties declared on the outermost theme root, for example
295
+ `box-shadow: var(--uai-elevation-1)`. They do not depend on the theme. Standalone entries are
296
+ `blip-tokens/css/shadows` and `blip-tokens/scss/shadows`.
297
+
298
+ Shadow layers retain their Figma order, RGB colors, opacity and pixel geometry.
299
+ For example, `--uai-elevation-3` contains two comma-separated shadows;
300
+ CSS, SCSS, JSON and JavaScript all expose the complete composition.
301
+
302
+ ### Typography
303
+
304
+ The design system does not generate utility classes. A text style in Figma is a
305
+ role (`body/base`, `heading/lg`, …) plus a weight, so components compose text
306
+ from the semantic variables:
307
+
308
+ ```css
309
+ .card-title {
310
+ font-family: var(--uai-font-family-sans);
311
+ font-size: var(--uai-title-font-size);
312
+ line-height: var(--uai-title-line-height);
313
+ font-weight: var(--uai-font-weight-semibold);
314
+ letter-spacing: var(--uai-letter-spacing-normal);
315
+ }
316
+ ```
317
+
318
+ The 28 Figma text styles are published as metadata only. Each entry in
319
+ `textStyles` names the variables that make it up, so a component can match its
320
+ Figma text style exactly:
321
+
322
+ ```ts
323
+ textStyles['uai-typography-title-semibold'].tokens;
324
+ // { fontFamily: '--uai-font-family-sans', fontSize: '--uai-title-font-size',
325
+ // lineHeight: '--uai-title-line-height', fontWeight: '--uai-font-weight-semibold',
326
+ // letterSpacing: '--uai-letter-spacing-normal' }
327
+ ```
328
+
329
+ The build fails if a text style stops matching its role and weight variables, so
330
+ Figma cannot drift from the published values. Display text uses
331
+ `--uai-font-family-display`; the spaced body style uses
332
+ `--uai-letter-spacing-expanded`.
333
+
334
+ ### JavaScript, TypeScript and token JSON
335
+
336
+ ```ts
337
+ import { light, dark, type TokenName } from 'blip-tokens/tokens';
338
+
339
+ const name: TokenName = 'uai-body-base-font-size';
340
+ console.log(light[name]); // "0.875rem"
341
+ console.log(dark['uai-surface-background']);
342
+ ```
343
+
344
+ The ESM entry `blip-tokens/tokens` exports `light`, `dark`, `shadows`, `textStyles`
345
+ and `metadata`. The package root still resolves to the icon entry. Theme maps
346
+ contain resolved web values (strings or numbers); they do not switch themes
347
+ automatically.
348
+
349
+ `blip-tokens/tokens/light` and `blip-tokens/tokens/dark` export normalized DTCG
350
+ JSON with semantic descriptions, dimension objects in px and sRGB color objects.
351
+ They contain no Foundation tokens; references to Foundation are resolved. The
352
+ web-oriented metadata object is also available as
353
+ `blip-tokens/tokens/metadata`:
354
+
355
+ ```ts
356
+ import { metadata, shadows, textStyles } from 'blip-tokens/tokens';
357
+
358
+ metadata['uai-surface-background'];
359
+ // { description, type, collection, scopes, figmaVariableId }
360
+
361
+ textStyles['uai-typography-body-base-regular'];
362
+ // { name, fontFamily, fontSize, lineHeight, fontWeight, letterSpacing, description, figmaStyleId, tokens }
363
+
364
+ shadows['uai-elevation-1'];
365
+ // { value, description, figmaStyleId }
366
+ ```
367
+
368
+ Descriptions explain intended use and should be specific enough to guide design
369
+ and implementation decisions. The build rejects missing descriptions so that
370
+ the token API remains useful to people and AI tools. The original snapshot and
371
+ audit trail remain maintainer-only and are not packed into npm. DTCG files are
372
+ design-token data, not the transformed web maps. SCSS variables are available via the
373
+ `blip-tokens/scss/colors-light`, `scss/colors-dark`, `scss/typography`,
374
+ `scss/dimensions` and `scss/shadows` package entries using a package-aware Sass
375
+ resolver. They hold static values, so prefer the CSS variables for themed styles.
376
+
377
+ ### Unit policy
378
+
379
+ | Usage | Source/normalized DTCG | Web output |
380
+ |---|---|---|
381
+ | Font size and line height | px | rem, at 16 px per rem |
382
+ | Spacing, sizing, radius | px | rem, at 16 px per rem |
383
+ | Border width | px | px |
384
+ | Shadow geometry | px | px |
385
+ | Letter spacing / font tracking | px | px |
386
+ | Opacity and font weight | number | number |
387
+
388
+ The current Figma tracking primitives explicitly document pixels; do not infer
389
+ `em` or percent from their numeric values. A future change requires an explicit
390
+ policy and tests. Conversion is applied by semantic usage after resolving raw
391
+ aliases: a shared Foundation dimension can become `rem` when used as spacing,
392
+ sizing, radius or typography, while remaining `px` for border width. The build
393
+ does not change the application's root font size.
394
+
395
+ Raw Figma floats are preserved in the snapshot. Normalized numeric/color values
396
+ are rounded to six decimal places to remove serialization noise (for example,
397
+ `-0.4000000059604645` becomes `-0.4`).
398
+
399
+ ### Synchronization
400
+
401
+ Maintainers use the repository-internal
402
+ [tokens-sync skill](.github/skills/tokens-sync/SKILL.md) for **Figma to repository**
403
+ sync. There is no background sync or automatic write-back to Figma.
404
+
405
+ ```sh
406
+ # Assemble every exported chunk into a new candidate file outside the repository.
407
+ npm run tokens:collect -- /tmp/blip-candidate.json /tmp/blip-chunk-0.json /tmp/blip-chunk-40.json
408
+ # Preview only.
409
+ npm run tokens:sync -- /tmp/blip-candidate.json
410
+ # Apply reviewed changes and append the audit record.
411
+ npm run tokens:sync -- /tmp/blip-candidate.json --apply
412
+ ```
413
+
414
+ The collector example abbreviates the chunk list; pass all chunks until the
415
+ declared total is covered. The sync validates the complete snapshot, reports
416
+ before/after changes, and requires `--approve-breaking` in addition to `--apply`
417
+ for explicitly approved removals or renames. No-op exports leave the source and
418
+ audit untouched. Commit the snapshot and audit together; never edit the audit
419
+ by hand. Unknown types, missing modes, broken aliases, cycles and naming
420
+ collisions fail the build instead of being silently skipped.
421
+
422
+ Composite Figma styles are exported and synced independently because they are
423
+ not variable collections. The styles workflow maintains its own snapshot and
424
+ hash-linked audit:
425
+
426
+ ```sh
427
+ npm run tokens:styles:sync -- /tmp/blip-styles-candidate.json
428
+ npm run tokens:styles:sync -- /tmp/blip-styles-candidate.json --apply
429
+ ```
430
+
431
+ Style removals and renames also require explicit approval and
432
+ `--approve-breaking`. Inventory changes require updating the compiler and tests
433
+ before applying the snapshot.
434
+
435
+ Style snapshot schema 2 stores each effect row as
436
+ `[id, name, description, layers]`, where each layer is
437
+ `[x, y, blur, spread, red, green, blue, alpha]`. Layers are ordered and nonempty;
438
+ the exporter rejects hidden effects and effects other than `DROP_SHADOW`.
439
+ Text rows retain their existing format. Schema 1 remains readable so historical
440
+ snapshot hashes and the audit chain are preserved.
441
+
442
+ The initial source is a fresh live export, not the UAI repository's snapshot.
443
+ Tokens that exist only in that other repository are not implicitly added here.
444
+
445
+ ### Figma library revision, 2026-10-16
446
+
447
+ This revision of the Figma library removes and renames variables and styles
448
+ relative to the earlier Figma snapshot. That snapshot was never published to
449
+ npm, and the `--uai-*` names are new, so no published consumer is affected:
450
+ existing consumers keep using the unchanged legacy outputs. Use this section
451
+ when migrating work-in-progress code that adopted earlier Figma names. There
452
+ are no compatibility aliases. Audit entries retain the exact before/after data
453
+ and original Figma IDs.
454
+
455
+ | Previous name | New name preserving the original variable/style ID |
456
+ |---|---|
457
+ | `spacing/6xl` (80 px) | `spacing/7xl` (80 px) |
458
+ | `spacing/7xl` (96 px) | `spacing/9xl` (96 px) |
459
+ | `letter-spacing/body` | `letter-spacing/normal` |
460
+ | `elevation/xs` | `elevation/floating-control` |
461
+ | `elevation/sm` | `elevation/tab-active` |
462
+ | `elevation/md` | `elevation/1` |
463
+ | `elevation/lg` | `elevation/2` |
464
+ | `elevation/xl` | `elevation/dialog` |
465
+ | `elevation/2xl` | `elevation/sidebar-right` |
466
+
467
+ The new `spacing/6xl` is 72 px (4.5 rem), not the previous 80 px; the existing
468
+ `spacing/7xl` name now resolves to 80 px (5 rem), not 96 px. Update consumers
469
+ explicitly to preserve their intended geometry. New spacing tokens include
470
+ `spacing/8xl` at 88 px (5.5 rem). Renamed shadows also have revised geometry;
471
+ renaming alone does not preserve their previous appearance.
472
+
473
+ Removed public variables:
474
+
475
+ - Dimensions: `sizing/5xl`, `sizing/6xl`, `border-width/thin`,
476
+ `border-width/medium`, `border-width/heavy`.
477
+ - Typography: `display/font-family`, `heading/xl/font-family`,
478
+ `heading/lg/font-family`, `heading/md/font-family`, `title/font-family`,
479
+ `body/lg/font-family`, `body/base/font-family`, `body/sm/font-family`,
480
+ `caption/font-family`, `overline/font-family`, `body/lg/font-size`,
481
+ `body/lg/line-height`, `body/sm/font-size`, `body/sm/line-height`,
482
+ `font-weight/light`, `letter-spacing/heading`.
483
+ - Colors: `surface/foreground`, `surface/paper-foreground`, `surface/brand`,
484
+ `surface/brand-foreground`, `surface/muted-foreground`, `surface/elevated`,
485
+ `surface/elevated-foreground`, `surface/accent`, `surface/accent-foreground`,
486
+ `content/heading`, `action/secondary/default`, `action/secondary/hover`,
487
+ `action/secondary/pressed`, `action/secondary/foreground`, `border/subtle`,
488
+ `feedback/destructive`.
489
+
490
+ Replacements, where the values are equivalent. The eight `body/lg/*` and
491
+ `body/sm/*` text styles have the same values as `title/*` and `caption/*`:
492
+
493
+ | Removed | Use instead |
494
+ |---|---|
495
+ | `uai-typography-body-lg-{regular,medium,semibold,bold}` (16/24) | `uai-typography-title-*` with the same weight |
496
+ | `uai-typography-body-sm-{regular,medium,semibold,bold}` (12/20) | `uai-typography-caption-*` with the same weight |
497
+ | `--uai-*-font-family` | `--uai-font-family-sans`, or `--uai-font-family-display` for display text |
498
+ | `--uai-letter-spacing-heading` | `--uai-letter-spacing-normal` |
499
+ | `--uai-surface-brand` / `--uai-surface-brand-foreground` | `--uai-fixed-brand` / `--uai-fixed-bright` |
500
+ | `--uai-border-subtle` | `--uai-border-default`; in dark mode this is `slate.850` instead of `slate.800` |
501
+ | `--uai-border-width-heavy` (4 px) | `--uai-border-width-thick` (2 px); the stroke is thinner |
502
+
503
+ The remaining removals have no one-to-one replacement. Choose a semantic variable
504
+ from its usage description. New styles include `elevation/3` and
505
+ `elevation/sidebar-left`; `content/inverse` is the new semantic foreground for
506
+ inverted surfaces. Retained color paths keep their Light and Dark values.
92
507
 
93
508
  ---
94
509
 
@@ -103,6 +518,22 @@ There are two icon variants:
103
518
  | **Outline** | `assets/icons/outline/` | `<name>-outline` |
104
519
  | **Solid** | `assets/icons/solid/` | `<name>-solid` |
105
520
 
521
+ ### UAI Icon font
522
+
523
+ The separate UAI icon set lives in `assets/uai-icons/outline/` and `assets/uai-icons/solid/`. Its SVGs are uploaded to the versioned CDN. The generated monochrome WOFF2 font and glyph data are published under `uai-icon/font/` and `uai-icon/glyphs.json` in the CDN. The npm package bundles only the CSS under `build/uai-icons/`, exported as `blip-tokens/uai-icons/css`; the CSS references the versioned CDN font. The legacy `assets/icons/` registry, names, and build remain independent.
524
+
525
+ The generated font uses `currentColor`, so icon color follows the CSS `color` property of the element (or an inherited color). Import the bundled stylesheet, then use the base class, glyph class, and a size class. The WOFF2 font and glyph manifest are available from the versioned CDN; only the stylesheet is included in the package.
526
+
527
+ ```html
528
+ <link rel="stylesheet" href="node_modules/blip-tokens/build/uai-icons/uai-icon.css">
529
+ <i class="uai-icon uai-icon-outline-favorite uai-icon-32" aria-hidden="true"></i>
530
+ <span class="uai-icon uai-icon-solid-favorite uai-icon-24" style="color: #e2483d" aria-hidden="true"></span>
531
+ ```
532
+
533
+ Supported size classes are `uai-icon-16`, `uai-icon-24`, and `uai-icon-32`. The glyph class is `uai-icon-<variant>-<name>`; when two icons share a leaf name, the category is included to disambiguate, for example `uai-icon-outline-file-video` and `uai-icon-outline-media-video`.
534
+
535
+ The build generates the font source from the UAI SVGs, replacing their monochrome fill/stroke colors with `currentColor`; transparent fills such as `fill="none"` are preserved. This transformation is isolated to the font source and does not modify the shipped UAI SVG assets.
536
+
106
537
  ### Adding New Icons
107
538
 
108
539
  1. **Place the SVG file** in the correct folder:
@@ -270,41 +701,67 @@ During `npm publish`, `prepublishOnly` also passes npm's `npm_package_version`
270
701
  explicitly to the asset generator. This preserves the exact release version even
271
702
  when the publish lifecycle does not receive `CDN_ASSETS_VERSION`.
272
703
 
273
- The build clears previous outputs and runs three steps:
704
+ The build clears previous outputs and runs four steps:
274
705
 
275
- 1. **Style Dictionary** (`config.cjs`) — transforms only color and theme tokens into JSON, CSS, and SCSS; artwork registries are not inputs
706
+ 1. **Style Dictionary 2** (`config.cjs`) — transforms only color and theme tokens into the legacy JSON, CSS, and SCSS; artwork registries are not inputs
276
707
  2. **Icon types generator** (`scripts/generate_icon_types.js`) — produces `build/icons.js` and `build/icons.d.ts`
277
- 3. **CDN asset generator** (`scripts/generate_assets.cjs`) — reads the SVG source registries directly, validates and copies artwork, and generates the asset manifest without intermediate embedded JSON catalogs
708
+ 3. **Figma token pipeline** (`scripts/build_tokens.js`) — validates the Figma snapshot, normalizes DTCG, resolves aliases and generates the `--uai-*` outputs with Style Dictionary 5. It runs after step 1 and writes only `uai-*` files, `tokens.js` and `tokens.d.ts`, so the legacy files are not touched
709
+ 4. **CDN asset generator** (`scripts/generate_assets.cjs`) — reads the SVG source registries directly, validates and copies artwork, and generates the asset manifest without intermediate embedded JSON catalogs
710
+
711
+ Style Dictionary 5 is installed as the `style-dictionary-v5` alias next to
712
+ Style Dictionary 2, which the legacy and asset builds still use. Run `npm test`
713
+ for the Figma pipeline tests together with the asset and release tests.
278
714
 
279
715
  ### Build Outputs
280
716
 
717
+ Outputs are grouped by format. Figma-derived files carry the `uai-` prefix and sit
718
+ next to the legacy files, which keep their original names and paths:
719
+
281
720
  ```
282
721
  build/
283
722
  ├── css/
284
- │ └── classes.css # CSS utility classes (.color-*, .bg-*)
723
+ │ ├── uai.css # Entry: imports the four uai-* files below
724
+ │ ├── uai-colors.css # Color variables: one block per theme root
725
+ │ ├── uai-typography.css # Typography variables, outermost theme root
726
+ │ ├── uai-dimensions.css # Spacing, sizing, radius and border width, outermost theme root
727
+ │ ├── uai-shadows.css # Elevation variables, outermost theme root
728
+ │ └── classes.css # Legacy color and background classes
285
729
  ├── scss/
286
- │ ├── variables.scss # Color palette as SCSS variables
287
- │ ├── theme-light.scss
288
- │ ├── theme-dark.scss
289
- │ ├── theme-high-contrast.scss
290
- │ └── extended-color.scss
730
+ │ ├── uai-colors-light.scss # $uai-* color variables, light values
731
+ │ ├── uai-colors-dark.scss # $uai-* color variables, dark values
732
+ │ ├── uai-typography.scss
733
+ │ ├── uai-dimensions.scss
734
+ │ ├── uai-shadows.scss
735
+ │ └── theme-*.scss, variables.scss, extended-color.scss # Legacy palette and themes
291
736
  ├── json/
292
- │ ├── variables.json # Flat JSON of non-artwork tokens
293
- │ ├── colors.json
294
- │ ├── theme-light.json
295
- │ ├── theme-dark.json
296
- │ ├── theme-high-contrast.json
297
- │ └── extended-color.json
737
+ │ ├── uai-light.tokens.json # Semantic DTCG with resolved aliases
738
+ │ ├── uai-dark.tokens.json
739
+ │ ├── uai-metadata.json # Figma descriptions, scopes and IDs
740
+ │ ├── uai-shadows.json # Eight composed elevation styles
741
+ │ ├── uai-text-styles.json # 28 text styles and the variables that compose each
742
+ │ ├── variables.json # Legacy flat JSON of non-artwork tokens
743
+ │ ├── colors.json # Legacy palette
744
+ │ ├── theme-*.json # Legacy themes (light, dark, high-contrast)
745
+ │ └── extended-color.json # Legacy extended palette
298
746
  ├── assets/v1/
299
- │ ├── manifest.json # Packaged CDN paths, sizes, and hashes
747
+ │ ├── manifest.json # Packaged inventory; used for validation, not uploaded
300
748
  │ └── .../*.svg # CDN upload only; excluded from npm
749
+ ├── tokens.js # ESM theme maps, styles and metadata
750
+ ├── tokens.d.ts # Token, style and metadata types
301
751
  ├── icons.js # Runtime icon arrays + helpers
302
752
  └── icons.d.ts # TypeScript type definitions
303
753
  ```
304
754
 
305
755
  The npm package contains design tokens, icon names and types, path-only source registries, and the CDN manifest exported as `blip-tokens/assets/manifest`. The build does not generate the old embedded-SVG `assets_*.json` or illustration JSON catalogs. Consumers of those catalogs must resolve artwork through the CDN manifest instead.
306
756
 
307
- Packaging uses `.npmignore` exclusions instead of a per-file `package.json` allowlist, so new token outputs are included automatically. Raw SVGs, raw source artwork, legacy embedded-artwork catalogs, and development files are excluded from npm. The standalone SVGs remain in `build/assets/v1` for CDN upload; packaging does not delete them. Tests inspect a real npm archive to check that tokens and exports remain available without raw or embedded SVG artwork.
757
+ Packaging uses `.npmignore` exclusions instead of a per-file `package.json` allowlist, so new token outputs are included automatically. Raw SVGs, raw source artwork, legacy embedded-artwork catalogs, and development files (including `figma-source/`, `tests/` and `docs/`) are excluded from npm. The standalone SVGs remain in `build/assets/v1` for CDN upload; packaging does not delete them. Tests inspect a real npm archive to check that tokens and exports remain available without raw or embedded SVG artwork.
758
+
759
+ Consumers of the Figma tokens import through the package `exports` (for example
760
+ `blip-tokens/css` or `blip-tokens/css/colors`), which map to the `uai-*`
761
+ files, so file names can change without affecting them. The legacy outputs are
762
+ exposed by path through `blip-tokens/build/css/*`, `blip-tokens/build/scss/*`
763
+ and `blip-tokens/build/json/*`. The package root (`blip-tokens`) still resolves
764
+ to the icon entry; the token maps are at `blip-tokens/tokens`.
308
765
 
309
766
  ---
310
767
 
@@ -312,7 +769,7 @@ Packaging uses `.npmignore` exclusions instead of a per-file `package.json` allo
312
769
 
313
770
  - **Workflow:** `.github/workflows/nodejs.yml`
314
771
  - **Triggers:** Pushes to `main`, pushes of `v*` tags, pull requests targeting `main`, and manual dispatch. Fork pull requests do not run the reusable CI job.
315
- - **Pipeline:** Delegates to the shared Node workflow with Node.js 24, `npm run test:ci`, `npm run lint`, and `npm run build`.
772
+ - **Pipeline:** Delegates to the shared Node workflow with Node.js 24, `npm run test:ci`, `npm run lint`, and `npm run build`. `test:ci` and `lint` cover the Figma token pipeline as well as the asset scripts.
316
773
  - **Test reports:** `test:ci` writes JUnit to `TestResults/junit.xml` and LCOV to `TestResults/coverage/lcov.info`.
317
774
  - **CDN:** Publishes `build/assets/v1` using release versioning. Shared conventions supply the build version; release preparation builds and uploads the exact upcoming release before npm publication.
318
775
  - **npm:** [Semantic Release](https://github.com/semantic-release/semantic-release) publishes to `https://registry.npmjs.org/` using the `PUBLIC_NPM_TOKEN` secret. The `prepublishOnly` lifecycle rebuilds with npm's exact package version.