@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.
- package/CHANGELOG.md +140 -0
- package/README.md +99 -15
- package/dist/android/colors.xml +1 -1
- package/dist/css/colors-hex-brand-rnd.css +2 -2
- package/dist/css/colors-hex-brand.css +2 -2
- package/dist/css/colors-hex-default.css +2 -2
- package/dist/css/colors-hex-label.css +2 -2
- package/dist/css/colors-hex-status.css +2 -2
- package/dist/css/colors-hex-theme.css +2 -2
- package/dist/css/colors-hex-tones.css +2 -2
- package/dist/css/colors-hex.css +2 -2
- package/dist/css/colors-rgb-brand-rnd.css +2 -2
- package/dist/css/colors-rgb-brand.css +2 -2
- package/dist/css/colors-rgb-default.css +2 -2
- package/dist/css/colors-rgb-label.css +2 -2
- package/dist/css/colors-rgb-status.css +2 -2
- package/dist/css/colors-rgb-theme.css +2 -2
- package/dist/css/colors-rgb-tones.css +2 -2
- package/dist/css/colors-rgb.css +2 -2
- package/dist/css/tailwind-theme-color.css +2 -2
- package/dist/css/tailwind-theme-typography.css +2 -2
- package/dist/css/transitions.css +2 -2
- package/dist/css/typography.css +2 -2
- package/dist/dtcg/base.tokens.json +14309 -0
- package/dist/dtcg/contrast-more.tokens.json +224 -0
- package/dist/dtcg/magma.resolver.json +85 -0
- package/dist/dtcg/mode-dark.tokens.json +6274 -0
- package/dist/dtcg/theme-cool-contrast-more.tokens.json +56 -0
- package/dist/dtcg/theme-cool.tokens.json +226 -0
- package/dist/dtcg/theme-warm-contrast-more.tokens.json +56 -0
- package/dist/dtcg/theme-warm.tokens.json +226 -0
- package/dist/flutter/colors-brand-rnd.dart +2 -2
- package/dist/flutter/colors-brand.dart +2 -2
- package/dist/flutter/colors-default.dart +2 -2
- package/dist/flutter/colors-label.dart +2 -2
- package/dist/flutter/colors-status.dart +2 -2
- package/dist/flutter/colors-theme.dart +2 -2
- package/dist/flutter/colors-tones.dart +2 -2
- package/dist/flutter/colors.dart +2 -2
- package/dist/flutter/fonts.dart +2 -2
- package/dist/ios/StyleDictionaryColor.h +1 -1
- package/dist/ios/StyleDictionaryColor.m +1 -1
- package/dist/ios-swift/StyleDictionary.swift +1 -1
- package/dist/ios-swift/StyleDictionaryColor.swift +1 -1
- package/dist/js/colors-css-vars.js +2 -2
- package/dist/js/tailwind-colors-css-vars.js +2 -2
- package/dist/js/tailwind-font-family.js +2 -2
- package/dist/js/tailwind-font-size.js +2 -2
- package/dist/js/tailwind-leading.js +2 -2
- package/dist/js/tailwind-props.js +2 -2
- package/dist/js/tailwind-screens.js +2 -2
- package/dist/json/coolors.json +1 -1
- package/dist/package.json +11 -10
- package/dist/playground/assets/index-CBGr93ts.js +198 -0
- package/dist/playground/index.html +1 -1
- package/dist/scss/variables.scss +1 -1
- package/package.json +11 -10
- 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.
|
|
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
|
-
|
|
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
|
-
"
|
|
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
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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.
|
|
146
|
-
color.<group>.<name>.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" }`:
|
|
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 |
|
|
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
|
|
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
|
|
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
|
|
package/dist/android/colors.xml
CHANGED
package/dist/css/colors-hex.css
CHANGED
package/dist/css/colors-rgb.css
CHANGED
package/dist/css/transitions.css
CHANGED
package/dist/css/typography.css
CHANGED