blip-tokens 2.0.1 → 2.1.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 +471 -28
- package/build/assets/v1/manifest.json +1 -1
- package/build/css/uai-colors.css +163 -0
- package/build/css/uai-dimensions.css +72 -0
- package/build/css/uai-shadows.css +18 -0
- package/build/css/uai-typography.css +52 -0
- package/build/css/uai.css +4 -0
- package/build/json/uai-dark.tokens.json +2078 -0
- package/build/json/uai-light.tokens.json +2078 -0
- package/build/json/uai-metadata.json +955 -0
- package/build/json/uai-shadows.json +42 -0
- package/build/json/uai-text-styles.json +478 -0
- 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/uai-colors-dark.scss +39 -0
- package/build/scss/uai-colors-light.scss +39 -0
- package/build/scss/uai-dimensions.scss +35 -0
- package/build/scss/uai-shadows.scss +8 -0
- package/build/scss/uai-typography.scss +25 -0
- package/build/scss/variables.scss +1 -1
- package/build/tokens.d.ts +12 -0
- package/build/tokens.js +1677 -0
- package/package.json +29 -24
- package/properties/assets/components.json +11 -0
- package/properties/assets/emojis.json +114 -0
- package/properties/assets/icons.json +2091 -0
- package/properties/assets/illustrations.json +2044 -0
- package/properties/assets/logos.json +192 -0
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/ #
|
|
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 #
|
|
63
|
-
│ ├── theme-light.json #
|
|
64
|
-
│ ├── theme-dark.json #
|
|
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
|
-
├──
|
|
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
|
-
|
|
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` |
|
|
88
|
-
| `theme-light.json` |
|
|
89
|
-
| `theme-dark.json` |
|
|
90
|
-
| `theme-high-contrast.json` |
|
|
91
|
-
| `extended-color.json` |
|
|
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
|
|
|
@@ -270,39 +685,67 @@ During `npm publish`, `prepublishOnly` also passes npm's `npm_package_version`
|
|
|
270
685
|
explicitly to the asset generator. This preserves the exact release version even
|
|
271
686
|
when the publish lifecycle does not receive `CDN_ASSETS_VERSION`.
|
|
272
687
|
|
|
273
|
-
The build clears previous outputs and runs
|
|
688
|
+
The build clears previous outputs and runs four steps:
|
|
274
689
|
|
|
275
|
-
1. **Style Dictionary** (`config.cjs`) — transforms only color and theme tokens into JSON, CSS, and SCSS; artwork registries are not inputs
|
|
690
|
+
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
691
|
2. **Icon types generator** (`scripts/generate_icon_types.js`) — produces `build/icons.js` and `build/icons.d.ts`
|
|
277
|
-
3. **
|
|
692
|
+
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
|
|
693
|
+
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
|
|
694
|
+
|
|
695
|
+
Style Dictionary 5 is installed as the `style-dictionary-v5` alias next to
|
|
696
|
+
Style Dictionary 2, which the legacy and asset builds still use. Run `npm test`
|
|
697
|
+
for the Figma pipeline tests together with the asset and release tests.
|
|
278
698
|
|
|
279
699
|
### Build Outputs
|
|
280
700
|
|
|
701
|
+
Outputs are grouped by format. Figma-derived files carry the `uai-` prefix and sit
|
|
702
|
+
next to the legacy files, which keep their original names and paths:
|
|
703
|
+
|
|
281
704
|
```
|
|
282
705
|
build/
|
|
283
706
|
├── css/
|
|
284
|
-
│
|
|
707
|
+
│ ├── uai.css # Entry: imports the four uai-* files below
|
|
708
|
+
│ ├── uai-colors.css # Color variables: one block per theme root
|
|
709
|
+
│ ├── uai-typography.css # Typography variables, outermost theme root
|
|
710
|
+
│ ├── uai-dimensions.css # Spacing, sizing, radius and border width, outermost theme root
|
|
711
|
+
│ ├── uai-shadows.css # Elevation variables, outermost theme root
|
|
712
|
+
│ └── classes.css # Legacy color and background classes
|
|
285
713
|
├── scss/
|
|
286
|
-
│ ├──
|
|
287
|
-
│ ├──
|
|
288
|
-
│ ├──
|
|
289
|
-
│ ├──
|
|
290
|
-
│
|
|
714
|
+
│ ├── uai-colors-light.scss # $uai-* color variables, light values
|
|
715
|
+
│ ├── uai-colors-dark.scss # $uai-* color variables, dark values
|
|
716
|
+
│ ├── uai-typography.scss
|
|
717
|
+
│ ├── uai-dimensions.scss
|
|
718
|
+
│ ├── uai-shadows.scss
|
|
719
|
+
│ └── theme-*.scss, variables.scss, extended-color.scss # Legacy palette and themes
|
|
291
720
|
├── json/
|
|
292
|
-
│ ├──
|
|
293
|
-
│ ├──
|
|
294
|
-
│ ├──
|
|
295
|
-
│ ├──
|
|
296
|
-
│ ├──
|
|
297
|
-
│
|
|
721
|
+
│ ├── uai-light.tokens.json # Semantic DTCG with resolved aliases
|
|
722
|
+
│ ├── uai-dark.tokens.json
|
|
723
|
+
│ ├── uai-metadata.json # Figma descriptions, scopes and IDs
|
|
724
|
+
│ ├── uai-shadows.json # Eight composed elevation styles
|
|
725
|
+
│ ├── uai-text-styles.json # 28 text styles and the variables that compose each
|
|
726
|
+
│ ├── variables.json # Legacy flat JSON of non-artwork tokens
|
|
727
|
+
│ ├── colors.json # Legacy palette
|
|
728
|
+
│ ├── theme-*.json # Legacy themes (light, dark, high-contrast)
|
|
729
|
+
│ └── extended-color.json # Legacy extended palette
|
|
298
730
|
├── assets/v1/
|
|
299
731
|
│ ├── manifest.json # Packaged CDN paths, sizes, and hashes
|
|
300
732
|
│ └── .../*.svg # CDN upload only; excluded from npm
|
|
733
|
+
├── tokens.js # ESM theme maps, styles and metadata
|
|
734
|
+
├── tokens.d.ts # Token, style and metadata types
|
|
301
735
|
├── icons.js # Runtime icon arrays + helpers
|
|
302
736
|
└── icons.d.ts # TypeScript type definitions
|
|
303
737
|
```
|
|
304
738
|
|
|
305
|
-
The npm package contains design tokens, icon names and types, and the CDN manifest exported as `blip-tokens/assets/manifest`.
|
|
739
|
+
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.
|
|
740
|
+
|
|
741
|
+
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.
|
|
742
|
+
|
|
743
|
+
Consumers of the Figma tokens import through the package `exports` (for example
|
|
744
|
+
`blip-tokens/css` or `blip-tokens/css/colors`), which map to the `uai-*`
|
|
745
|
+
files, so file names can change without affecting them. The legacy outputs are
|
|
746
|
+
exposed by path through `blip-tokens/build/css/*`, `blip-tokens/build/scss/*`
|
|
747
|
+
and `blip-tokens/build/json/*`. The package root (`blip-tokens`) still resolves
|
|
748
|
+
to the icon entry; the token maps are at `blip-tokens/tokens`.
|
|
306
749
|
|
|
307
750
|
---
|
|
308
751
|
|
|
@@ -310,7 +753,7 @@ The npm package contains design tokens, icon names and types, and the CDN manife
|
|
|
310
753
|
|
|
311
754
|
- **Workflow:** `.github/workflows/nodejs.yml`
|
|
312
755
|
- **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.
|
|
313
|
-
- **Pipeline:** Delegates to the shared Node workflow with Node.js 24, `npm run test:ci`, `npm run lint`, and `npm run build`.
|
|
756
|
+
- **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.
|
|
314
757
|
- **Test reports:** `test:ci` writes JUnit to `TestResults/junit.xml` and LCOV to `TestResults/coverage/lcov.info`.
|
|
315
758
|
- **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.
|
|
316
759
|
- **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.
|