@maggioli-design-system/design-tokens 15.0.1 → 15.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.
Files changed (58) hide show
  1. package/CHANGELOG.md +140 -0
  2. package/README.md +99 -15
  3. package/dist/android/colors.xml +1 -1
  4. package/dist/css/colors-hex-brand-rnd.css +2 -2
  5. package/dist/css/colors-hex-brand.css +2 -2
  6. package/dist/css/colors-hex-default.css +2 -2
  7. package/dist/css/colors-hex-label.css +2 -2
  8. package/dist/css/colors-hex-status.css +2 -2
  9. package/dist/css/colors-hex-theme.css +2 -2
  10. package/dist/css/colors-hex-tones.css +2 -2
  11. package/dist/css/colors-hex.css +2 -2
  12. package/dist/css/colors-rgb-brand-rnd.css +2 -2
  13. package/dist/css/colors-rgb-brand.css +2 -2
  14. package/dist/css/colors-rgb-default.css +2 -2
  15. package/dist/css/colors-rgb-label.css +2 -2
  16. package/dist/css/colors-rgb-status.css +2 -2
  17. package/dist/css/colors-rgb-theme.css +2 -2
  18. package/dist/css/colors-rgb-tones.css +2 -2
  19. package/dist/css/colors-rgb.css +2 -2
  20. package/dist/css/tailwind-theme-color.css +2 -2
  21. package/dist/css/tailwind-theme-typography.css +2 -2
  22. package/dist/css/transitions.css +2 -2
  23. package/dist/css/typography.css +2 -2
  24. package/dist/dtcg/base.tokens.json +14309 -0
  25. package/dist/dtcg/contrast-more.tokens.json +224 -0
  26. package/dist/dtcg/magma.resolver.json +85 -0
  27. package/dist/dtcg/mode-dark.tokens.json +6274 -0
  28. package/dist/dtcg/theme-cool-contrast-more.tokens.json +56 -0
  29. package/dist/dtcg/theme-cool.tokens.json +226 -0
  30. package/dist/dtcg/theme-warm-contrast-more.tokens.json +56 -0
  31. package/dist/dtcg/theme-warm.tokens.json +226 -0
  32. package/dist/flutter/colors-brand-rnd.dart +2 -2
  33. package/dist/flutter/colors-brand.dart +2 -2
  34. package/dist/flutter/colors-default.dart +2 -2
  35. package/dist/flutter/colors-label.dart +2 -2
  36. package/dist/flutter/colors-status.dart +2 -2
  37. package/dist/flutter/colors-theme.dart +2 -2
  38. package/dist/flutter/colors-tones.dart +2 -2
  39. package/dist/flutter/colors.dart +2 -2
  40. package/dist/flutter/fonts.dart +2 -2
  41. package/dist/ios/StyleDictionaryColor.h +1 -1
  42. package/dist/ios/StyleDictionaryColor.m +1 -1
  43. package/dist/ios-swift/StyleDictionary.swift +1 -1
  44. package/dist/ios-swift/StyleDictionaryColor.swift +1 -1
  45. package/dist/js/colors-css-vars.js +2 -2
  46. package/dist/js/tailwind-colors-css-vars.js +2 -2
  47. package/dist/js/tailwind-font-family.js +2 -2
  48. package/dist/js/tailwind-font-size.js +2 -2
  49. package/dist/js/tailwind-leading.js +2 -2
  50. package/dist/js/tailwind-props.js +2 -2
  51. package/dist/js/tailwind-screens.js +2 -2
  52. package/dist/json/coolors.json +1 -1
  53. package/dist/package.json +11 -10
  54. package/dist/playground/assets/index-CBGr93ts.js +198 -0
  55. package/dist/playground/index.html +1 -1
  56. package/dist/scss/variables.scss +1 -1
  57. package/package.json +11 -10
  58. package/dist/playground/assets/index-DxckacQQ.js +0 -198
package/CHANGELOG.md ADDED
@@ -0,0 +1,140 @@
1
+ # Changelog
2
+
3
+ Every release of `@maggioli-design-system/design-tokens`, newest first. Each section is the body of the GitHub
4
+ release with the same tag, written by git-cliff from the conventional commits of the
5
+ package.
6
+
7
+ ## [design-tokens@15.2.0] - 2026-10-15
8
+
9
+ ### Build
10
+
11
+ - *(design-tokens,identity,styles,svg-icons,icons,magma)* Ship CHANGELOG.md in every package
12
+
13
+ ### Features
14
+
15
+ - *(design-tokens)* Describe every semantic role and group in the DTCG export
16
+
17
+ ## [design-tokens@15.1.0] - 2026-10-14
18
+
19
+ ### Documentation
20
+
21
+ - *(magma,styles,design-tokens)* Rewrite the color docs on the semantic layer
22
+ - *(magma,styles,design-tokens)* Align the styles and design-tokens docs with the build
23
+
24
+ ### Features
25
+
26
+ - *(design-tokens)* Export every global token as DTCG 2025.10 JSON
27
+
28
+ ### Refactor
29
+
30
+ - *(design-tokens,styles)* Build the semantic layer as data in design-tokens
31
+ - *(design-tokens)* Export the DTCG helpers the styles globals reuse
32
+
33
+ ## [design-tokens@15.0.1] - 2026-10-05
34
+
35
+ ### Bug Fixes
36
+
37
+ - *(design-tokens)* Import the scale helpers in the playground themes section
38
+
39
+ ## [design-tokens@15.0.0] - 2026-09-30
40
+
41
+ ### Bug Fixes
42
+
43
+ - *(design-tokens)* Stop deepMerge from mutating module-level defaults
44
+ - *(design-tokens)* Make the published cli runnable
45
+ - *(design-tokens)* Keep the new-color dialog open on outside clicks
46
+ - *(design-tokens)* Make token export deterministic and writes reliable
47
+ - *(design-tokens)* Clear error when a color references an undefined ratios scale
48
+ - *(design-tokens)* Flag only real overrides in the groups view
49
+ - *(design-tokens)* Hide the playground picker in surfaces, groups and diff
50
+ - *(design-tokens)* Preview the neutral ink on colored surfaces, not #000
51
+ - *(design-tokens)* Playground surface preview - one family at a time, step charts on top
52
+ - *(design-tokens)* Retune the text targets so no two text roles collapse onto one step
53
+ - *(design-tokens)* Spell the leonardo background color name correctly
54
+
55
+ ### Changes
56
+
57
+ - *(design-tokens)* Raise the hue shift angle limit to 180 degrees
58
+ - *(design-tokens)* Easing-based distribution modes for contrast scales
59
+ - *(design-tokens)* Name colors via color-namer in the playground
60
+ - *(design-tokens)* Restructure playground navigation around colors, scales and groups
61
+ - *(design-tokens)* Select the first involved color when switching scale
62
+ - *(design-tokens)* Tag built-in-only ratio scales in the playground selects
63
+ - *(design-tokens)* Retune the default surface, border and text ramp
64
+
65
+ ### Documentation
66
+
67
+ - *(design-tokens)* Add configuration reference and generation model to readme
68
+ - *(design-tokens)* Document the nx playground target
69
+
70
+ ### Features
71
+
72
+ - *(design-tokens)* Add GIMP palette format and update configuration for design tokens
73
+ - *(design-tokens)* Add hue shifting support to color token generation
74
+ - *(design-tokens)* Add config playground with live palette preview
75
+ - *(design-tokens)* Make hue shift inheritance explicit in the playground
76
+ - *(design-tokens)* Load and download configs from the playground
77
+ - *(design-tokens)* Manage contrast scales in the playground
78
+ - *(design-tokens)* Full easing set and free scale deletion in the playground
79
+ - *(design-tokens)* Auto-name colors from their value in the playground
80
+ - *(design-tokens)* Create colors from a picker dialog in the playground
81
+ - *(design-tokens)* Group-level ratios and formula
82
+ - *(design-tokens)* Download generated tokens as a zip from the playground
83
+ - *(design-tokens)* Download menu with per-format token exports
84
+ - *(design-tokens)* Group-level export targets
85
+ - *(design-tokens)* Diversify CSS and GIMP downloads per export group
86
+ - *(design-tokens)* Batch export editing across groups in the playground
87
+ - *(design-tokens)* Toggle to show only selected color scales in groups
88
+ - *(design-tokens)* Add `ui` command serving the playground with a config API
89
+ - *(design-tokens)* Save, persist and reset the playground config in the ui
90
+ - *(design-tokens)* Add a JSON Schema and validate configs against it
91
+ - *(design-tokens)* Add a diff view to the playground
92
+ - *(design-tokens)* Group selected colors on top in the groups view
93
+ - *(design-tokens)* Export Figma color tokens in the DTCG standard format
94
+ - *(design-tokens)* Download DTCG Figma tokens from the playground
95
+ - *(design-tokens)* Flag built-in contrast scales in the playground
96
+ - *(design-tokens)* Lightness-based surface + border token engine (#571)
97
+ - *(design-tokens)* Explicit contrast bounds + ratio validation (#578)
98
+ - *(design-tokens)* Usable-band visualization in the scales playground (#578)
99
+ - *(design-tokens)* Surface editor view in the playground (#571)
100
+ - *(design-tokens)* Explain each semantic role in the surfaces view (#571)
101
+ - *(design-tokens)* [**breaking**] Emit --tone-*-seed for the pure extreme (#572)
102
+ - *(design-tokens)* Add by-target text-role engine (#591)
103
+ - *(design-tokens)* Text roles in the playground surface view (#591)
104
+ - *(design-tokens)* Add APCA contrast gate for semantic pairs (#575)
105
+ - *(design-tokens)* Add surface preview aids to the playground
106
+ - *(design-tokens)* Pick text-role step by worst-case surface (A7)
107
+ - *(design-tokens)* Back a foreground from any surface-opted family, not just tone
108
+ - *(design-tokens)* Derive themes from the surfaces opt-in in the playground
109
+ - *(design-tokens)* Slider per i lightness levels nel playground
110
+ - *(design-tokens)* Add the themes map to the semantic config
111
+ - *(design-tokens)* Make variant reference its source via the alias field
112
+ - *(design-tokens)* Declare the accent roles and gate their contrast
113
+ - *(design-tokens)* Alias-aware colors editor in playground
114
+ - *(design-tokens)* Declare accent interaction-state steps and gate them
115
+ - *(design-tokens)* Add shared accent theme-override helper and playground accent section
116
+ - *(design-tokens,stencil,styles)* Collapse accent roles to {accent, ai}
117
+ - *(design-tokens)* Enforce variant alias-only model in playground
118
+ - *(design-tokens)* Two-column themes workbench with tabbed preview
119
+ - *(design-tokens)* Opt a whole group into surfaces, with status always on
120
+ - *(design-tokens)* Promote semantic roles under pref-contrast-more
121
+ - *(design-tokens,styles,stencil)* Publish the hue role scales and promote them under pref-contrast-more
122
+ - *(design-tokens)* Retune the border ramp and gate it in the playground
123
+ - *(design-tokens,styles,stencil)* Retint the raw ramp with the theme via --magma-scale-*
124
+ - *(design-tokens,styles,stencil)* Give the colored hues the emphasis band states
125
+ - *(design-tokens,styles)* Give the neutral pills a wash band
126
+ - *(design-tokens,styles,stencil)* A shadow ink role, the ring family back, and a guard
127
+ - *(design-tokens)* Add the radius scale tuned for the squircle
128
+ - *(design-tokens)* Take the page to the paper of the mode under contrast-more
129
+ - *(design-tokens)* Move the accent ink to step 03
130
+ - *(design-tokens)* Add the less marked level of the inverse surface
131
+
132
+ ### Refactor
133
+
134
+ - *(design-tokens)* Retune built-in wcag3 ratios within the APCA band
135
+ - *(design-tokens)* Rifinisci il layout degli slider dei lightness levels
136
+ - *(design-tokens,styles,stencil)* Name the hue background levels wash-*, not surface-*
137
+
138
+ ### Styling
139
+
140
+ - *(design-tokens)* Cap hue shift slider width in the playground
package/README.md CHANGED
@@ -11,7 +11,8 @@ Use the version of this package matching the major version of [`@maggioli-design
11
11
  | magma | design-tokens | styles |
12
12
  | :--- | :--- | :--- |
13
13
  | `1.x` (before Magma 2) | `13.x` (latest `13.7.2`) | `15.x` (latest `15.11.1`) |
14
- | `2.x` and later | `>= 14` | `>= 16` |
14
+ | `2.0.0-alpha.0` to `2.0.0-beta.3` (prereleases) | `14.x` | `16.x` |
15
+ | `2.x` and later | `>= 15` | `>= 17` |
15
16
 
16
17
  # Installation
17
18
 
@@ -27,6 +28,59 @@ This package works also with yarn:
27
28
  yarn add @maggioli-design-system/design-tokens
28
29
  ```
29
30
 
31
+ # Token data (DTCG)
32
+
33
+ `dist/dtcg/` describes every global token of Magma in the [Design Tokens Community Group format, version 2025.10](https://www.designtokens.org/TR/2025.10/): the primitives of this package, the semantic layer (`--magma-*`) that `@maggioli-design-system/styles` publishes, and what changes in dark mode, under a named theme and under `prefers-contrast: more`. Read it to show, document or transform the tokens (a documentation site, a design tool, another platform). To style a page, use the stylesheets: the JSON describes them, it does not replace them.
34
+
35
+ | File | Content |
36
+ | :--- | :--- |
37
+ | `magma.resolver.json` | Which sets to merge, and in which order, for one mode and one theme ([resolver module](https://www.designtokens.org/TR/2025.10/resolver/)) |
38
+ | `base.tokens.json` | Every token, in light mode and in the default theme |
39
+ | `mode-dark.tokens.json` | What dark mode changes: the palette, the ring shadows, the ink on solid fills |
40
+ | `contrast-more.tokens.json` | The `pref-contrast-more` promotions of the default theme |
41
+ | `theme-<name>.tokens.json` | What a named theme (`data-theme-name`) repoints |
42
+ | `theme-<name>-contrast-more.tokens.json` | The contrast promotions of that theme, in its own family |
43
+
44
+ Each set lists only what it changes. To get the tokens of one condition, merge the files that `resolutionOrder` names (the `base` set, then the `mode` context, then the `theme` context), let a later file replace a token of an earlier one, and resolve the aliases last. The result has the values the stylesheets give in the same condition, and a test checks it at every build.
45
+
46
+ | Modifier | Contexts |
47
+ | :--- | :--- |
48
+ | `mode` | `light` (default), `dark` |
49
+ | `theme` | `default` (default), `cool`, `warm`, and each of them with `-contrast-more` |
50
+
51
+ The theme and the contrast preference are one modifier because they are not independent: under a named theme, the stylesheets restate the contrast promotions in the theme's own family. Dark mode with the `cool` theme and more contrast, for example, merges `base`, `mode-dark`, `contrast-more`, `theme-cool` and `theme-cool-contrast-more`.
52
+
53
+ ## Token tree
54
+
55
+ | Path | Custom property | Content |
56
+ | :--- | :--- | :--- |
57
+ | `palette.<group>.<family>.<step>` | `--tone-neutral-08` | The color primitives. The family's own color is `$root` (`--status-info`), the paper of the mode is `seed`. Aliased families (`variant`) are aliases of the family they name. |
58
+ | `magma.<group>.<key>` | `--magma-surface-default` | The semantic roles, as aliases of the primitive they point at. `magma.tint` holds the internal `--magma-tint-*` pointers that themes and contrast repoint; an accent with an infix is a group of its own (`magma.accent-ai`). |
59
+ | `font.<family>` | `--font-title` | Font families. |
60
+ | `text-size.<family>.<style>` | `--text-size-title-h1` | The size of a style (`$root`) and its `font-weight`, `letter-spacing`, `line-height`. |
61
+ | `typography.<family>.<style>` | none | The same style as one `typography` token. |
62
+ | `leading`, `spacing`, `container`, `breakpoint`, `aspect`, `border`, `radius`, `shadow`, `duration`, `ease` | `--leading-md`, `--spacing-xs`, ... | One group per CSS prefix. `spacing.$root` is `--spacing`, the multiplier of the numeric utilities. |
63
+ | `size.<step>` | none | The primitive sizing scale that spacing, container, border and radius name. |
64
+
65
+ Every token carries `$extensions["it.maggioli.magma"]`:
66
+
67
+ - `css`: the custom property it is published as;
68
+ - `tier`: `primitive` (a raw value or scale), `semantic` (a `--magma-*` role, what UI code paints with) or `internal` (a `--magma-tint-*` pointer, not an API);
69
+ - `cssValue`: the CSS value, only where the CSS writes the same quantity differently.
70
+
71
+ Where the JSON and the CSS write a value differently:
72
+
73
+ - **Colors**: the CSS publishes channels (`--tone-neutral-08: 208 208 208`, read as `rgb(var(--tone-neutral-08))`); the JSON gives sRGB components and the hex.
74
+ - **Letter spacing**: the CSS writes it in `em`, which DTCG does not allow; the JSON gives it in `rem` at the style's own font size, and keeps the `em` in `cssValue`.
75
+ - **Line height** of a `typography` token: a multiplier of the font size, as DTCG defines it. The `line-height` token of the style keeps the length.
76
+ - **Aspect ratios**: a `number` (`5/3` becomes `1.6666666666666667`); `cssValue` keeps the ratio.
77
+ - **Ring shadows** (`--shadow-ring*`): the CSS draws them with `--tone-neutral-01`; the JSON resolves that color, so `mode-dark` restates them.
78
+ - **No DTCG type**: the text measures `--spacing-phrase`, `-prose`, `-text`, `-title` (in `ch`) and the `--transition-property-*` lists are listed in the `cssOnly` extension of their group.
79
+
80
+ Component tokens (`--mds-*`) are not in this data: they belong to each component.
81
+
82
+ The globals `@maggioli-design-system/styles` declares on top of these (the `--magma-*` of its `globals.css`, the corner and depth axes) are in its own `dist/dtcg/`, with a resolver that adds them to these sets, and how each token is consumed through Tailwind is its `dist/tailwind/consumption.json`, keyed by the same `css` names (its README, "Token data").
83
+
30
84
  # Generate Custom Palette
31
85
 
32
86
  you can generate custom palettes via cli command, it takes a configuration file to create palettes
@@ -46,8 +100,12 @@ npx magma-design-tokens
46
100
  | `--generate [platform]` | `-g` | Output format for palette, choose one or more between `css`, `tailwind`, `dart` |
47
101
  | `--export-tokens` | `-t` | export palette as JSON design tokens format |
48
102
  | `--outTokensDir [tokensDir]` | | Directory path for JSON tokens, required if `--export-tokens` is presents |
103
+ | `--dry-run` | | With `--export-tokens`: print the JSON tokens to stdout instead of writing them |
49
104
  | `--port [port]` | `-p` | Port for the `ui` command playground server (default `5178`) |
50
105
 
106
+ `npx magma-design-tokens ui` starts the playground on your configuration instead (see
107
+ [UI command](#ui-command)).
108
+
51
109
  ## Configuration file
52
110
 
53
111
  You can include configuration in a configuration file or a field in `package.json` named `magma-design-tokens`
@@ -119,17 +177,26 @@ You can choose the ratio with which to generate the color scale with `ratios` fi
119
177
  }
120
178
  ```
121
179
 
122
- NOTE: there are four different ratios as follow value contrast
180
+ The built-in ratio scales, per contrast `formula` (the default formula is `wcag3`, so a
181
+ `ratios` name resolves against the `wcag3` scales unless the color sets `"formula":
182
+ "wcag2"`):
123
183
 
124
184
  ```json
125
185
  {
126
- "v1": [
186
+ "wcag3": {
187
+ "default": [8, 16, 23, 34, 45, 66, 74, 84, 92, 100],
188
+ "tint": [8, 16, 23, 34, 45, 66, 74, 84, 92, 100],
189
+ "tone": [8, 15, 25, 36, 48, 71, 80, 91, 101, 106]
190
+ },
191
+ "wcag2": {
192
+ "v1": [
127
193
  1.05, 1.1, 1.17, 1.24, 1.32, 1.41, 1.51, 1.65, 1.9, 2.25, 2.7, 3.3,
128
194
  4, 4.8, 5.75, 7, 8.5, 10.3, 12.45, 15
129
195
  ],
130
- "v2": [1.09, 1.22, 1.42, 1.82, 2.57, 3.71, 5.13, 6.71, 8.75, 10.29],
131
- "default": [1.09, 1.22, 1.42, 1.82, 3.29, 5.13, 6.71, 8.45, 10.29, 17.22],
132
- "tone": [1.05, 1.1, 1.24, 1.47, 2.54, 4.83, 7.56, 10.31, 14.68, 16]
196
+ "v2": [1.09, 1.22, 1.42, 1.82, 2.57, 3.71, 5.13, 6.71, 8.75, 10.29],
197
+ "default": [1.09, 1.22, 1.42, 1.82, 3.29, 5.13, 6.71, 8.45, 10.29, 17.22],
198
+ "tone": [1.05, 1.1, 1.24, 1.47, 2.54, 4.83, 7.56, 10.31, 14.68, 16]
199
+ }
133
200
  }
134
201
  ```
135
202
 
@@ -142,10 +209,23 @@ Each color produces this token structure (here with the 10-step `default` scale)
142
209
  ```
143
210
  color.<group>.<name>.light.1 .. 10 contrast-picked values against white
144
211
  color.<group>.<name>.dark.1 .. 10 contrast-picked values against black
145
- color.<group>.<name>.light.color the base color itself (or seed.light)
146
- color.<group>.<name>.dark.color the base color itself (or seed.dark)
212
+ color.<group>.<name>.light.seed seed.light, when the color declares a `seed`
213
+ color.<group>.<name>.dark.seed seed.dark, when the color declares a `seed`
214
+ color.<group>.<name>.light.color otherwise: the base color itself
215
+ color.<group>.<name>.dark.color otherwise: the base color itself
147
216
  ```
148
217
 
218
+ In CSS these become `--<group>-<name>-01` ... `-10`, plus `--<group>-<name>-seed` (e.g.
219
+ `--tone-neutral-seed`) or the bare `--<group>-<name>` (e.g. `--brand-maggioli`).
220
+
221
+ A color can also opt into the **surface engine** (`surface`, below). Surfaces are not
222
+ contrast-solved: they are placed by a direct OKLCH lightness per mode and role, from the
223
+ root `theme` block, and each opted-in family additionally emits
224
+ `--surface-<name>-{sunken,muted,default,raised,overlay}`,
225
+ `--border-<name>-{muted,default,strong}` and `--text-<name>-{default,muted,subtle,disabled}`
226
+ (text roles solved by APCA target against that family's own surfaces). These families are
227
+ what the semantic color layer of `@maggioli-design-system/styles` points at.
228
+
149
229
  ### Configuration reference
150
230
 
151
231
  Root fields:
@@ -159,6 +239,7 @@ Root fields:
159
239
  | `ratios` | `object` | built-in | Named ratio scales per formula; merged over the built-in ones shown above |
160
240
  | `groups` | `object` | none | Per-group defaults for `ratios` and `formula`, keyed by token group (see below) |
161
241
  | `hueShift` | `object` | none | Default hue shifting applied to all colors (see the Hue shifting section) |
242
+ | `theme` | `object` | none | The surface engine: `surfaces` and `borders` (OKLCH lightness per mode and role, e.g. `"96%"`), `text` (APCA target per text role, or `{ "step": N }`), `colorspace`. Without it a `surface` opt-in is skipped with a warning |
162
243
 
163
244
  Fields of each entry in `colors` (per-color values override the root defaults):
164
245
 
@@ -171,13 +252,14 @@ Fields of each entry in `colors` (per-color values override the root defaults):
171
252
  | `formula` | `string` | root `formula` | Contrast formula for this color only |
172
253
  | `colorspace` | `string` | root value | Interpolation colorspace for this color only |
173
254
  | `smooth` | `boolean` | root value | Bezier smoothing for this color only |
174
- | `seed` | `object` | none | `{ "light": "#RRGGBB", "dark": "#RRGGBB" }`: overrides the value of the extra `color` token per theme mode. Used by tones to expose the pure surface color (white in light mode, black in dark mode) |
255
+ | `seed` | `object` | none | `{ "light": "#RRGGBB", "dark": "#RRGGBB" }`: emits the off-scale `seed` token instead of `color`. Used by tones for the pure extreme of the mode (white in light, black in dark): `--tone-neutral-seed`. It is not a surface |
256
+ | `surface` | `boolean` \| `object` | `false` | Opts the family into the surface engine (see How generation works): `true` uses the root `theme` levels, `{ "surfaces": {...}, "borders": {...} }` overrides them for this family. Also settable per group |
175
257
  | `hueShift` | `object` | root value | Hue shifting for this color only; set angles to `0` to opt a color out of a root-level default |
176
258
  | `disabled` | `boolean` | `false` | Skips the color entirely: no tokens are generated for it |
177
259
  | `title` | `string` | none | Reserved for exporters; not used by the generator |
178
- | `alias` | `string` | none | Reserved for exporters; not used by the generator |
260
+ | `alias` | `string` | none | `<group>.<name>` of another color: this entry carries no `color` and re-exports the source family's generated scale under its own name (`variant.primary` -> `brand.maggioli`) |
179
261
 
180
- Ratios, formula and export targets can also be set once per token group instead of repeating them on every color:
262
+ Ratios, formula, export targets and `surface` can also be set once per token group instead of repeating them on every color:
181
263
 
182
264
  ```json
183
265
  {
@@ -244,6 +326,8 @@ In Figma, create a variable collection and import each file into its own mode (L
244
326
 
245
327
  The non-color sizing/number tokens are still exported in the legacy Figma "Import/Export Variables" plugin format (`dist/json/figma-magma-tokens.json`); moving them to DTCG is tracked separately.
246
328
 
329
+ These files follow an earlier DTCG draft (colors as hex strings) and cover the palette only. Every global token, the semantic layer included, is in [`dist/dtcg/`](#token-data-dtcg).
330
+
247
331
  ### Playground
248
332
 
249
333
  A local UI to explore and tune the configuration with live palette previews:
@@ -254,7 +338,7 @@ nx run design-tokens:playground
254
338
  npm run playground -w projects/design-tokens
255
339
  ```
256
340
 
257
- It opens a Vite dev server (port 5177) that loads `.magma-design-tokensrc.json` and runs the real token generator in the browser, so every preview matches the build output exactly. The UI has four views: **colors** (the two-column editor: color list on the left, editing and live light/dark scale previews with achieved contrast on the right; `neutral` is selected by default when present), **contrast scales**, **groups** and **diff**. Selecting a color from the sidebar while in contrast scales keeps you there, since the scale samples follow the selected color.
341
+ It opens a Vite dev server (port 5177) that loads `.magma-design-tokensrc.json` and runs the real token generator in the browser, so every preview matches the build output exactly. The UI has five views: **colors** (the two-column editor: color list on the left, editing and live light/dark scale previews with achieved contrast on the right; `neutral` is selected by default when present), **contrast scales**, **themes** (opt families into the surface engine, tune the surface/border/text levels, and preview each opted family as a named theme with its accent assignment and contrast checks), **groups** and **diff**. Selecting a color from the sidebar while in contrast scales keeps you there, since the scale samples follow the selected color.
258
342
 
259
343
  The **diff** view compares the current palette against the one generated from the committed configuration (the bundled `.magma-design-tokensrc.json`): it lists the colors whose steps changed - outlining each changed step and badging the color with the largest perceptual distance (deltaE) - plus any colors added or removed. The generated token files under `tokens/color/generated/` are build artifacts and not committed, so the committed config is the baseline.
260
344
 
@@ -300,17 +384,17 @@ In this mode the playground loads the on-disk configuration on start and swaps *
300
384
 
301
385
  - takes `./color.js` as configuration file
302
386
  ```bash
303
- npx design-tokens --config ./color.js
387
+ npx magma-design-tokens --config ./color.js
304
388
  ```
305
389
 
306
390
  - export palette only on css format
307
391
  ```bash
308
- npx design-tokens --generate css
392
+ npx magma-design-tokens --generate css
309
393
  ```
310
394
 
311
395
  - export palette on css and tailwind format
312
396
  ```bash
313
- npx design-tokens --generate 'css, tailwind'
397
+ npx magma-design-tokens --generate 'css, tailwind'
314
398
  ```
315
399
 
316
400
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!--
4
4
  Do not edit directly
5
- Generated on Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated on Thu, 15 Oct 2026 16:06:42 GMT
6
6
  -->
7
7
  <resources>
8
8
  <color name="color_tone_porcelain_light_1">#ff040506</color>
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  @theme {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:10 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  @theme {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:11 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {
@@ -1,8 +1,8 @@
1
1
  /*
2
- @magma-design-system/design-tokens v15.0.1
2
+ @magma-design-system/design-tokens v15.2.0
3
3
  Generated by Style Dictionary
4
4
  Do not edit directly
5
- Generated at Mon, 05 Oct 2026 09:27:11 GMT
5
+ Generated at Thu, 15 Oct 2026 16:06:42 GMT
6
6
  */
7
7
 
8
8
  :root {