@uncinq/design-tokens 1.6.1 → 1.7.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 (5) hide show
  1. package/README.md +37 -16
  2. package/dist/css/semantic/gradient.css +14 -0
  3. package/dist/css/semantic.css +1 -0
  4. package/package.json +1 -1
  5. package/tokens/semantic/gradient.json +30 -0
package/README.md CHANGED
@@ -10,7 +10,7 @@ Design tokens are the atomic decisions of a design system: colors, spacing, typo
10
10
 
11
11
  ## Token architecture
12
12
 
13
- This package follows the [DTCG](docs/dtcg.md) three-layer model — primitive → semantic → component:
13
+ This package follows the [DTCG](docs/DTCG.md) three-layer model — primitive → semantic → component:
14
14
 
15
15
  ```
16
16
  primitive → semantic → component
@@ -72,13 +72,13 @@ Global semantic tokens follow: `--{category}-{subcategory?}-{variant}-{state?}`
72
72
 
73
73
  Component tokens follow: `--{component}-{property}-{sub-property?}-{state?}`
74
74
 
75
- The property mirrors the CSS property name — `background-color`, `border-color`, `text-decoration-color` — so the token reads the same way as the CSS declaration it controls.
75
+ The property mirrors the CSS property name, so the token reads the same way as the CSS declaration it controls — colors excepted, where `color` leads and the role follows (see the rules below).
76
76
 
77
77
  ```
78
78
  --{component} --btn
79
- -{property} --btn-background-color
80
- -{sub-property} --btn-text-decoration-color (text-decoration + color)
81
- -{state} --btn-background-color-hover
79
+ -{property} --btn-padding-inline
80
+ -{sub-property} --btn-color-text-decoration (color + text-decoration)
81
+ -{state} --btn-color-background-hover
82
82
  ```
83
83
 
84
84
  ### Rules
@@ -133,8 +133,9 @@ The property mirrors the CSS property name — `background-color`, `border-color
133
133
  | `spacing` | Margin / padding | `--spacing-md`, `--spacing-section` |
134
134
  | `size` | Width / height | `--size-16`, `--size-tablet` |
135
135
  | `radius` | Border radius | `--radius-md`, `--radius-pill` |
136
- | `border` | Border style/width | `--border-width-normal`, `--border-style-normal` |
136
+ | `border` | Border style/width | `--border-width-sm`, `--border-style-normal` |
137
137
  | `shadow` | Box shadows | `--shadow-md`, `--shadow-center-sm` |
138
+ | `gradient` | Overlay gradients | `--gradient-darken-color-from`, `--gradient-darken-stop` |
138
139
  | `duration` | Animation timing | `--duration-fast` |
139
140
  | `easing` | Timing functions | `--easing-bounce` |
140
141
  | `transition` | Shorthand transitions | `--transition-normal`, `--transition-color` |
@@ -168,7 +169,7 @@ All primitive color values are defined in **OKLCH** (`oklch(L C H)`):
168
169
  - **Better interpolation** — gradients and animations between two OKLCH colors don't pass through muddy grays.
169
170
  - **Future-proof** — native in all modern browsers, the color space used by Tailwind v4, Radix, and the W3C Design Tokens spec.
170
171
 
171
- > Browser support: Chrome 111+, Firefox 113+, Safari 15.4+. Legacy browsers receive the nearest sRGB fallback automatically.
172
+ > Browser support: Chrome 111+, Firefox 113+, Safari 15.4+. No sRGB fallback is generated — every value ships as `oklch()`, so anything older needs a fallback of its own.
172
173
 
173
174
  ### Primitive palette
174
175
 
@@ -314,19 +315,35 @@ Each variant has `-muted` (tinted bg) and `-strong` (hover / emphasis) companion
314
315
  - **Warning (amber-500)** — always pair with `--color-text-on-warning` (gray-900). Never white text on amber-500.
315
316
  - **Decorative only** — any step is fine when color carries no information (icons, borders, illustrations).
316
317
 
317
- ### Adding a custom hue
318
+ ### Dark theme
318
319
 
319
- Add a new primitive scale in `tokens/primitive/color.css` following the existing pattern:
320
+ `tokens/themes/dark.json` re-declares 13 semantic color tokens — backgrounds, border, text, `--form-color-background`, and `--color-shadow`, which flips to white. The generated `dist/css/themes/dark.css` wraps them, still inside `@layer tokens`:
320
321
 
321
322
  ```css
322
- /* ── Coral — H ≈ 35° ──────────────────────────────────────────────── */
323
- --color-coral-50: oklch(0.975 0.014 35.0);
324
- --color-coral-100: oklch(0.948 0.032 35.0);
325
- /* … 11 steps … */
326
- --color-coral-950: oklch(0.225 0.078 35.0);
323
+ @media (prefers-color-scheme: dark) {
324
+ :root:not([data-color-scheme="light"]) { /* … */ }
325
+ }
326
+ ```
327
+
328
+ So the dark scheme follows the OS setting, and `data-color-scheme="light"` on `<html>` opts a page out of it. There is no forced-dark selector — the package never turns dark on a light OS. The theme comes with the full `index.css`; importing `css/semantic.css` alone leaves it out.
329
+
330
+ ### Adding a custom hue
331
+
332
+ Add a new primitive scale in `tokens/primitive/color.json`, following the existing pattern — one DTCG color object per step:
333
+
334
+ ```json
335
+ {
336
+ "color": {
337
+ "coral": {
338
+ "50": { "$value": { "colorSpace": "oklch", "components": [0.975, 0.014, 35.0] }, "$type": "color" },
339
+ "100": { "$value": { "colorSpace": "oklch", "components": [0.948, 0.032, 35.0] }, "$type": "color" },
340
+ "950": { "$value": { "colorSpace": "oklch", "components": [0.225, 0.078, 35.0] }, "$type": "color" }
341
+ }
342
+ }
343
+ }
327
344
  ```
328
345
 
329
- Then reference it in `tokens/semantic/color.css` or your project's `@layer tokens` override.
346
+ Run `npm run build`, then reference the generated `--color-coral-*` from `tokens/semantic/color.json` or from your project's own `@layer tokens` override.
330
347
 
331
348
  ---
332
349
 
@@ -436,6 +453,7 @@ tokens/
436
453
  color.json ← purposeful color aliases (--color-brand, --color-background…)
437
454
  focus.json ← focus ring tokens (color, style, width, offset)
438
455
  form.json ← form control tokens (input, label, checkbox, switch…)
456
+ gradient.json ← darkening overlay gradient (colors + responsive stops)
439
457
  grid.json ← columns, gap, flex fractions
440
458
  icon.json ← SVG icon tokens (data URI)
441
459
  motion.json ← duration, easing, transitions
@@ -447,6 +465,8 @@ tokens/
447
465
  spacing.json ← spacing scale + fluid clamp() aliases
448
466
  typography.json ← font-size scale (fixed + fluid), heading sizes
449
467
  z-index.json ← stacking order
468
+ themes/
469
+ dark.json ← dark color scheme overrides
450
470
  ```
451
471
 
452
472
  Generated CSS (`dist/css/` — built by `npm run build`, do not edit):
@@ -458,13 +478,14 @@ dist/css/
458
478
  semantic.css ← imports all semantic files
459
479
  primitive/ ← one file per tokens/primitive/*.json
460
480
  semantic/ ← one file per tokens/semantic/*.json
481
+ themes/ ← one file per tokens/themes/*.json
461
482
  ```
462
483
 
463
484
  ---
464
485
 
465
486
  ## References
466
487
 
467
- - [DTCG — format and concepts](docs/dtcg.md)
488
+ - [DTCG — format and concepts](docs/DTCG.md)
468
489
  - [DTCG specification](https://tr.designtokens.org/format/) — W3C Community Group draft
469
490
  - [Style Dictionary v5](https://styledictionary.com/) — token build pipeline, see [docs/STYLE-DICTIONARY.md](docs/STYLE-DICTIONARY.md)
470
491
  - [MDN: CSS cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers)
package/dist/css/semantic/gradient.css ADDED
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Do not edit directly, this file was auto-generated.
3
+ */
4
+
5
+ /* semantic/gradient.css */
6
+ @layer tokens {
7
+ :root {
8
+ --gradient-darken-color-from: var(--color-shadow-strong);
9
+ --gradient-darken-color-to: var(--color-shadow-light);
10
+ --gradient-darken-stop: 100%;
11
+ --gradient-darken-stop-tablet: 50%;
12
+ --gradient-darken-stop-desktop: 33%;
13
+ }
14
+ }
package/dist/css/semantic.css CHANGED
@@ -4,6 +4,7 @@
4
4
  @import "./semantic/color.css";
5
5
  @import "./semantic/focus.css";
6
6
  @import "./semantic/form.css";
7
+ @import "./semantic/gradient.css";
7
8
  @import "./semantic/grid.css";
8
9
  @import "./semantic/icon.css";
9
10
  @import "./semantic/motion.css";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uncinq/design-tokens",
3
- "version": "1.6.1",
3
+ "version": "1.7.0",
4
4
  "description": "Framework-agnostic design tokens — JSON DTCG primitive and semantic — CSS custom properties.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/tokens/semantic/gradient.json ADDED
@@ -0,0 +1,30 @@
1
+ {
2
+ "gradient": {
3
+ "darken": {
4
+ "color": {
5
+ "from": {
6
+ "$type": "color",
7
+ "$value": "{color.shadow.strong}"
8
+ },
9
+ "to": {
10
+ "$type": "color",
11
+ "$value": "{color.shadow.light}"
12
+ }
13
+ },
14
+ "stop": {
15
+ "default": {
16
+ "$type": "dimension",
17
+ "$value": "100%"
18
+ },
19
+ "tablet": {
20
+ "$type": "dimension",
21
+ "$value": "50%"
22
+ },
23
+ "desktop": {
24
+ "$type": "dimension",
25
+ "$value": "33%"
26
+ }
27
+ }
28
+ }
29
+ }
30
+ }