@casinogate/ui 1.8.3 → 1.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -125,11 +125,22 @@ Override CSS variables to match your brand:
125
125
 
126
126
  ### Understanding the Theming System
127
127
 
128
- The component library uses a **two-tier CSS variable system** for maximum flexibility:
128
+ The component library uses a **three-tier CSS variable system** organized in modular files for maximum flexibility and maintainability:
129
129
 
130
- #### 1. **Palette Variables** (Low-level)
130
+ ```
131
+ src/assets/css/
132
+ ├── root.css # Entry point (imports everything)
133
+ ├── tokens/
134
+ │ ├── primitives.css # Layer 1: Raw design values
135
+ │ ├── light.css # Layer 2: Light theme semantic tokens
136
+ │ └── dark.css # Layer 2: Dark theme overrides
137
+ └── tailwind/
138
+ └── theme.css # Layer 3: Tailwind utility mappings
139
+ ```
140
+
141
+ #### Layer 1: **Primitive Tokens** (`tokens/primitives.css`)
131
142
 
132
- Base color definitions in `:root` that you can override:
143
+ Raw design values that serve as the single source of truth:
133
144
 
134
145
  ```css
135
146
  :root {
@@ -141,22 +152,49 @@ Base color definitions in `:root` that you can override:
141
152
  --cg-ui-palette-primary-100: hsla(220, 80%, 38%, 1);
142
153
  --cg-ui-palette-primary-80: hsla(220, 80%, 50%, 1);
143
154
  --cg-ui-palette-primary-60: hsla(220, 80%, 64%, 1);
155
+
156
+ /* Base numbers for spacing, radius, blur */
157
+ --cg-ui-number-sm: 8;
158
+ --cg-ui-number-md: 12;
159
+ }
160
+ ```
161
+
162
+ #### Layer 2: **Semantic Tokens** (`tokens/light.css` & `tokens/dark.css`)
163
+
164
+ Theme-aware aliases that map intent to primitives and switch between light/dark modes:
165
+
166
+ ```css
167
+ /* tokens/light.css */
168
+ :root,
169
+ [data-theme='light'] {
170
+ --cg-ui-color-fg-darkest: var(--cg-ui-palette-neutral-100);
171
+ --cg-ui-color-bg-main: var(--cg-ui-palette-neutral-20);
172
+ --cg-ui-color-surface-primary: var(--cg-ui-palette-primary-80);
173
+ }
174
+
175
+ /* tokens/dark.css */
176
+ .dark,
177
+ [data-theme='dark'] {
178
+ --cg-ui-color-fg-darkest: var(--cg-ui-palette-neutral-10);
179
+ --cg-ui-color-bg-main: var(--cg-ui-palette-neutral-80);
144
180
  }
145
181
  ```
146
182
 
147
- #### 2. **Semantic Variables** (High-level)
183
+ #### Layer 3: **Tailwind Theme** (`tailwind/theme.css`)
148
184
 
149
- Purpose-driven variables that reference palette colors:
185
+ Maps semantic tokens to Tailwind utility classes:
150
186
 
151
187
  ```css
152
188
  @theme inline {
153
- /* Components use semantic names */
154
- --color-surface-primary: var(--cg-ui-palette-primary-80);
155
- --color-fg-primary: var(--cg-ui-palette-primary-80);
156
- --color-stroke-primary: var(--cg-ui-palette-primary-80);
189
+ /* Components use semantic names via Tailwind utilities */
190
+ --color-fg-darkest: var(--cg-ui-color-fg-darkest);
191
+ --color-bg-main: var(--cg-ui-color-bg-main);
192
+ --color-surface-primary: var(--cg-ui-color-surface-primary);
157
193
  }
158
194
  ```
159
195
 
196
+ This enables Tailwind classes like `text-fg-darkest`, `bg-bg-main`, `bg-surface-primary` that automatically adapt to light/dark themes.
197
+
160
198
  ### How to Customize Your Theme
161
199
 
162
200
  #### Method 1: Override Hue & Saturation (Recommended)
@@ -195,17 +233,17 @@ For precise control over individual shades:
195
233
 
196
234
  #### Method 3: Override Semantic Variables
197
235
 
198
- Target specific component contexts:
236
+ Target specific component contexts by overriding the semantic layer:
199
237
 
200
238
  ```css
201
239
  :root {
202
240
  /* Change button backgrounds without affecting other primary uses */
203
- --color-surface-primary: #ff6b6b;
204
- --color-surface-primary-active: #ff5252;
241
+ --cg-ui-color-surface-primary: #ff6b6b;
242
+ --cg-ui-color-surface-primary-active: #ff5252;
205
243
 
206
244
  /* Customize form field borders */
207
- --color-stroke-default: #d1d5db;
208
- --color-stroke-focus: #3b82f6;
245
+ --cg-ui-color-stroke-default: #d1d5db;
246
+ --cg-ui-color-stroke-focus: #3b82f6;
209
247
  }
210
248
  ```
211
249
 
@@ -296,21 +334,28 @@ The library includes a complete dark theme that activates with `.dark` class or
296
334
 
297
335
  #### Customizing Dark Mode Colors
298
336
 
299
- Override dark theme colors specifically:
337
+ Override dark theme colors in your application CSS. The library's dark mode is defined in `tokens/dark.css`:
300
338
 
301
339
  ```css
340
+ /* Your app's custom dark mode overrides */
302
341
  .dark,
303
342
  [data-theme='dark'] {
304
343
  /* Custom dark mode primary color */
305
344
  --cg-ui-primary-hue: 160; /* Teal in dark mode */
306
345
  --cg-ui-primary-saturation: 80%;
307
346
 
308
- /* Adjust neutral darkness */
347
+ /* Override palette colors */
309
348
  --cg-ui-palette-neutral-100: hsla(220, 50%, 5%, 1);
310
349
  --cg-ui-palette-neutral-80: hsla(220, 50%, 10%, 1);
350
+
351
+ /* Override semantic colors directly */
352
+ --cg-ui-color-fg-darkest: var(--cg-ui-palette-neutral-10);
353
+ --cg-ui-color-bg-main: var(--cg-ui-palette-neutral-100);
311
354
  }
312
355
  ```
313
356
 
357
+ **Note:** Dark mode activates when `.dark` class or `data-theme="dark"` attribute is present on an ancestor element.
358
+
314
359
  ---
315
360
 
316
361
  ## 📋 Complete CSS Variables Reference
@@ -389,80 +434,83 @@ Semantic colors for states and notifications.
389
434
 
390
435
  #### Semantic Color Variables
391
436
 
392
- Purpose-driven variables used directly by components (defined in `@theme inline`).
393
-
394
- ##### Surface Colors (Backgrounds)
395
-
396
- | Variable | References | Description |
397
- | -------------------------------------- | ----------------------------- | ---------------------------- |
398
- | `--color-surface-primary` | `--cg-ui-palette-primary-80` | Primary button background |
399
- | `--color-surface-primary-active` | `--cg-ui-palette-primary-60` | Primary button hover/active |
400
- | `--color-surface-primary-light` | `--cg-ui-palette-primary-40` | Light primary surface |
401
- | `--color-surface-primary-light-active` | `--cg-ui-palette-primary-10` | Light primary surface active |
402
- | `--color-surface-darkest` | `--cg-ui-palette-neutral-100` | Darkest surface |
403
- | `--color-surface-dark` | `--cg-ui-palette-neutral-80` | Dark surface |
404
- | `--color-surface-regular` | `--cg-ui-palette-neutral-50` | Regular surface |
405
- | `--color-surface-semilight` | `--cg-ui-palette-neutral-40` | Semi-light surface |
406
- | `--color-surface-light` | `--cg-ui-palette-neutral-20` | Light surface (cards) |
407
- | `--color-surface-lightest` | `--cg-ui-palette-neutral-10` | Lightest surface |
408
- | `--color-surface-white` | `--cg-ui-palette-neutral-0` | White surface |
409
- | `--color-surface-hover` | `--cg-ui-palette-neutral-01` | Hover overlay |
437
+ The semantic layer provides theme-aware aliases that automatically switch between light and dark modes.
410
438
 
411
- ##### Background Colors (Page-level)
412
-
413
- | Variable | References | Description |
414
- | ------------------ | ----------------------------- | -------------------- |
415
- | `--color-bg-white` | `--cg-ui-palette-neutral-0` | White background |
416
- | `--color-bg-main` | `--cg-ui-palette-neutral-20` | Main page background |
417
- | `--color-bg-dark` | `--cg-ui-palette-neutral-100` | Dark background |
439
+ **Architecture:** `Primitive` `Semantic (--cg-ui-color-*)` → `Tailwind (--color-*)`
418
440
 
419
441
  ##### Foreground Colors (Text)
420
442
 
421
- | Variable | References | Description |
422
- | ---------------------- | ------------------------------------ | -------------------- |
423
- | `--color-fg-darkest` | `--cg-ui-palette-neutral-100` | Primary text color |
424
- | `--color-fg-dark` | `--cg-ui-palette-neutral-80` | Dark text |
425
- | `--color-fg-medium` | `--cg-ui-palette-neutral-60` | Medium text |
426
- | `--color-fg-regular` | `--cg-ui-palette-neutral-50` | Regular text |
427
- | `--color-fg-semilight` | `--cg-ui-palette-neutral-40` | Light text |
428
- | `--color-fg-primary` | `--cg-ui-palette-primary-80` | Primary colored text |
429
- | `--color-fg-white` | `--cg-ui-palette-neutral-0` | White text |
430
- | `--color-fg-error` | `--cg-ui-palette-system-error-100` | Error text |
431
- | `--color-fg-success` | `--cg-ui-palette-system-success-100` | Success text |
443
+ | Semantic Variable (CSS) | Light Mode Reference | Dark Mode Override | Tailwind Class |
444
+ | ---------------------------- | ------------------------------------ | ---------------------------- | ------------------- |
445
+ | `--cg-ui-color-fg-darkest` | `--cg-ui-palette-neutral-100` | `--cg-ui-palette-neutral-10` | `text-fg-darkest` |
446
+ | `--cg-ui-color-fg-dark` | `--cg-ui-palette-neutral-80` | `--cg-ui-palette-neutral-10` | `text-fg-dark` |
447
+ | `--cg-ui-color-fg-medium` | `--cg-ui-palette-neutral-60` | `--cg-ui-palette-neutral-40` | `text-fg-medium` |
448
+ | `--cg-ui-color-fg-regular` | `--cg-ui-palette-neutral-50` | `--cg-ui-palette-neutral-20` | `text-fg-regular` |
449
+ | `--cg-ui-color-fg-semilight` | `--cg-ui-palette-neutral-40` | `--cg-ui-palette-neutral-40` | `text-fg-semilight` |
450
+ | `--cg-ui-color-fg-white` | `--cg-ui-palette-neutral-0` | `--cg-ui-palette-neutral-10` | `text-fg-white` |
451
+ | `--cg-ui-color-fg-primary` | `--cg-ui-palette-primary-80` | (inherited) | `text-fg-primary` |
452
+ | `--cg-ui-color-fg-error` | `--cg-ui-palette-system-error-100` | (inherited) | `text-fg-error` |
453
+ | `--cg-ui-color-fg-success` | `--cg-ui-palette-system-success-100` | (inherited) | `text-fg-success` |
454
+ | `--cg-ui-color-fg-warning` | `--cg-ui-palette-system-warning-100` | (inherited) | `text-fg-warning` |
455
+
456
+ ##### Background Colors (Page-level)
457
+
458
+ | Semantic Variable (CSS) | Light Mode Reference | Dark Mode Override | Tailwind Class |
459
+ | ------------------------ | ----------------------------- | ---------------------------- | -------------- |
460
+ | `--cg-ui-color-bg-white` | `--cg-ui-palette-neutral-0` | (inherited) | `bg-bg-white` |
461
+ | `--cg-ui-color-bg-main` | `--cg-ui-palette-neutral-20` | `--cg-ui-palette-neutral-80` | `bg-bg-main` |
462
+ | `--cg-ui-color-bg-dark` | `--cg-ui-palette-neutral-100` | (inherited) | `bg-bg-dark` |
463
+
464
+ ##### Surface Colors (Cards, Panels)
465
+
466
+ | Semantic Variable (CSS) | Light Mode Reference | Dark Mode Override | Tailwind Class |
467
+ | -------------------------------------------- | ----------------------------- | ---------------------------- | --------------------------------- |
468
+ | `--cg-ui-color-surface-primary` | `--cg-ui-palette-primary-80` | (inherited) | `bg-surface-primary` |
469
+ | `--cg-ui-color-surface-primary-active` | `--cg-ui-palette-primary-60` | (inherited) | `bg-surface-primary-active` |
470
+ | `--cg-ui-color-surface-primary-light` | `--cg-ui-palette-primary-40` | (inherited) | `bg-surface-primary-light` |
471
+ | `--cg-ui-color-surface-primary-light-active` | `--cg-ui-palette-primary-10` | (inherited) | `bg-surface-primary-light-active` |
472
+ | `--cg-ui-color-surface-darkest` | `--cg-ui-palette-neutral-100` | (inherited) | `bg-surface-darkest` |
473
+ | `--cg-ui-color-surface-dark` | `--cg-ui-palette-neutral-80` | (inherited) | `bg-surface-dark` |
474
+ | `--cg-ui-color-surface-regular` | `--cg-ui-palette-neutral-50` | (inherited) | `bg-surface-regular` |
475
+ | `--cg-ui-color-surface-semilight` | `--cg-ui-palette-neutral-40` | (inherited) | `bg-surface-semilight` |
476
+ | `--cg-ui-color-surface-light` | `--cg-ui-palette-neutral-20` | (inherited) | `bg-surface-light` |
477
+ | `--cg-ui-color-surface-lightest` | `--cg-ui-palette-neutral-10` | `--cg-ui-palette-neutral-80` | `bg-surface-lightest` |
478
+ | `--cg-ui-color-surface-white` | `--cg-ui-palette-neutral-0` | `--cg-ui-palette-neutral-60` | `bg-surface-white` |
479
+ | `--cg-ui-color-surface-hover` | `--cg-ui-palette-neutral-01` | (inherited) | `bg-surface-hover` |
432
480
 
433
481
  ##### Stroke Colors (Borders)
434
482
 
435
- | Variable | References | Description |
436
- | ------------------------ | ---------------------------------- | -------------------- |
437
- | `--color-stroke-default` | `--cg-ui-palette-neutral-40` | Default border color |
438
- | `--color-stroke-minimum` | `--cg-ui-palette-neutral-10` | Minimal border |
439
- | `--color-stroke-focus` | `--cg-ui-palette-primary-60` | Focus ring border |
440
- | `--color-stroke-primary` | `--cg-ui-palette-primary-80` | Primary border |
441
- | `--color-stroke-divider` | `--cg-ui-palette-neutral-20` | Divider lines |
442
- | `--color-stroke-error` | `--cg-ui-palette-system-error-100` | Error border |
483
+ | Semantic Variable (CSS) | Light Mode Reference | Dark Mode Override | Tailwind Class |
484
+ | ------------------------------ | ---------------------------------- | ---------------------------- | ----------------------- |
485
+ | `--cg-ui-color-stroke-default` | `--cg-ui-palette-neutral-40` | `--cg-ui-palette-neutral-50` | `border-stroke-default` |
486
+ | `--cg-ui-color-stroke-minimum` | `--cg-ui-palette-neutral-10` | (inherited) | `border-stroke-minimum` |
487
+ | `--cg-ui-color-stroke-focus` | `--cg-ui-palette-primary-60` | (inherited) | `border-stroke-focus` |
488
+ | `--cg-ui-color-stroke-primary` | `--cg-ui-palette-primary-80` | (inherited) | `border-stroke-primary` |
489
+ | `--cg-ui-color-stroke-divider` | `--cg-ui-palette-neutral-20` | `--cg-ui-palette-neutral-50` | `border-stroke-divider` |
490
+ | `--cg-ui-color-stroke-error` | `--cg-ui-palette-system-error-100` | (inherited) | `border-stroke-error` |
443
491
 
444
492
  ##### Icon Colors
445
493
 
446
- | Variable | References | Description |
447
- | ---------------------- | ---------------------------- | ------------------ |
448
- | `--color-icon-regular` | `--cg-ui-palette-neutral-50` | Regular icon color |
449
- | `--color-icon-default` | `--cg-ui-palette-neutral-40` | Default icon color |
450
- | `--color-icon-primary` | `--cg-ui-palette-primary-80` | Primary icon color |
451
- | `--color-icon-focus` | `--cg-ui-palette-primary-60` | Focused icon color |
452
- | `--color-icon-white` | `--cg-ui-palette-neutral-0` | White icon |
494
+ | Semantic Variable (CSS) | Light Mode Reference | Dark Mode Override | Tailwind Class |
495
+ | ---------------------------- | ---------------------------- | ---------------------------- | ------------------- |
496
+ | `--cg-ui-color-icon-regular` | `--cg-ui-palette-neutral-50` | `--cg-ui-palette-neutral-40` | `text-icon-regular` |
497
+ | `--cg-ui-color-icon-default` | `--cg-ui-palette-neutral-40` | (inherited) | `text-icon-default` |
498
+ | `--cg-ui-color-icon-primary` | `--cg-ui-palette-primary-80` | (inherited) | `text-icon-primary` |
499
+ | `--cg-ui-color-icon-focus` | `--cg-ui-palette-primary-60` | (inherited) | `text-icon-focus` |
500
+ | `--cg-ui-color-icon-white` | `--cg-ui-palette-neutral-0` | `--cg-ui-palette-neutral-40` | `text-icon-white` |
453
501
 
454
502
  ##### State Colors
455
503
 
456
- | Variable | References | Description |
457
- | ----------------------------- | ------------------------------------ | ------------------ |
458
- | `--color-state-error` | `--cg-ui-palette-system-error-100` | Error state |
459
- | `--color-state-error-light` | `--cg-ui-palette-system-error-10` | Error background |
460
- | `--color-state-warning` | `--cg-ui-palette-system-warning-100` | Warning state |
461
- | `--color-state-warning-light` | `--cg-ui-palette-system-warning-10` | Warning background |
462
- | `--color-state-success` | `--cg-ui-palette-system-success-100` | Success state |
463
- | `--color-state-success-light` | `--cg-ui-palette-system-success-10` | Success background |
464
- | `--color-state-info` | `--cg-ui-palette-system-info-100` | Info state |
465
- | `--color-state-info-light` | `--cg-ui-palette-system-info-10` | Info background |
504
+ | Semantic Variable (CSS) | Light Mode Reference | Dark Mode Override | Tailwind Class |
505
+ | ----------------------------------- | ------------------------------------ | ------------------ | ------------------------ |
506
+ | `--cg-ui-color-state-error` | `--cg-ui-palette-system-error-100` | (inherited) | `bg-state-error` |
507
+ | `--cg-ui-color-state-error-light` | `--cg-ui-palette-system-error-10` | (inherited) | `bg-state-error-light` |
508
+ | `--cg-ui-color-state-warning` | `--cg-ui-palette-system-warning-100` | (inherited) | `bg-state-warning` |
509
+ | `--cg-ui-color-state-warning-light` | `--cg-ui-palette-system-warning-10` | (inherited) | `bg-state-warning-light` |
510
+ | `--cg-ui-color-state-success` | `--cg-ui-palette-system-success-100` | (inherited) | `bg-state-success` |
511
+ | `--cg-ui-color-state-success-light` | `--cg-ui-palette-system-success-10` | (inherited) | `bg-state-success-light` |
512
+ | `--cg-ui-color-state-info` | `--cg-ui-palette-system-info-100` | (inherited) | `bg-state-info` |
513
+ | `--cg-ui-color-state-info-light` | `--cg-ui-palette-system-info-10` | (inherited) | `bg-state-info-light` |
466
514
 
467
515
  ### Typography
468
516
 
@@ -630,10 +678,12 @@ Responsive design breakpoints for media queries.
630
678
 
631
679
  <style>
632
680
  .custom-section {
633
- /* Override just for this section */
634
- --color-surface-primary: #ff6b6b;
635
- --color-surface-primary-active: #ff5252;
636
- --radius-sm: 16px;
681
+ /* Override semantic variables for this section */
682
+ --cg-ui-color-surface-primary: #ff6b6b;
683
+ --cg-ui-color-surface-primary-active: #ff5252;
684
+
685
+ /* Override primitive numbers for radius */
686
+ --cg-ui-number-sm: 16;
637
687
  }
638
688
  </style>
639
689
  ```
@@ -677,9 +727,9 @@ Responsive design breakpoints for media queries.
677
727
  import { DataTable } from '@casinogate/ui';
678
728
 
679
729
  const customColors = {
680
- '--color-surface-light': '#f0f9ff',
681
- '--color-stroke-default': '#bae6fd',
682
- '--radius-md': '12px',
730
+ '--cg-ui-color-surface-light': '#f0f9ff',
731
+ '--cg-ui-color-stroke-default': '#bae6fd',
732
+ '--cg-ui-number-md': '12',
683
733
  };
684
734
  </script>
685
735
 
@@ -842,8 +892,13 @@ packages/cg-ui/
842
892
  │ │ └── ...
843
893
  │ ├── assets/
844
894
  │ │ └── css/
845
- │ │ ├── root.css # Main entry point
846
- │ │ └── theme.css # CSS variables
895
+ │ │ ├── root.css # Main entry point
896
+ │ │ ├── tokens/
897
+ │ │ │ ├── primitives.css # Raw design values
898
+ │ │ │ ├── light.css # Light theme semantic tokens
899
+ │ │ │ └── dark.css # Dark theme overrides
900
+ │ │ └── tailwind/
901
+ │ │ └── theme.css # Tailwind utility mappings
847
902
  │ ├── internal/ # Internal utilities
848
903
  │ │ ├── types/ # TypeScript definitions
849
904
  │ │ └── utils/ # Helper functions
@@ -896,30 +951,58 @@ packages/cg-ui/
896
951
 
897
952
  ### Adding New CSS Variables
898
953
 
899
- 1. **Add to palette** (`:root` in `theme.css`)
954
+ Follow the three-tier architecture when adding new design tokens:
955
+
956
+ 1. **Add primitive token** (`tokens/primitives.css`)
900
957
 
901
958
  ```css
902
959
  :root {
903
960
  --cg-ui-palette-accent-100: hsla(180, 80%, 40%, 1);
961
+ --cg-ui-palette-accent-10: hsla(180, 80%, 94%, 1);
904
962
  }
905
963
  ```
906
964
 
907
- 2. **Add semantic variable** (`@theme inline` in `theme.css`)
965
+ 2. **Add semantic tokens for light theme** (`tokens/light.css`)
966
+
967
+ ```css
968
+ :root,
969
+ [data-theme='light'] {
970
+ --cg-ui-color-accent: var(--cg-ui-palette-accent-100);
971
+ --cg-ui-color-accent-subtle: var(--cg-ui-palette-accent-10);
972
+ }
973
+ ```
974
+
975
+ 3. **Add dark theme overrides if needed** (`tokens/dark.css`)
976
+
977
+ ```css
978
+ .dark,
979
+ [data-theme='dark'] {
980
+ --cg-ui-color-accent: var(--cg-ui-palette-accent-100);
981
+ --cg-ui-color-accent-subtle: var(--cg-ui-palette-accent-10);
982
+ }
983
+ ```
984
+
985
+ 4. **Map to Tailwind utilities** (`tailwind/theme.css`)
908
986
 
909
987
  ```css
910
988
  @theme inline {
911
- --color-accent: var(--cg-ui-palette-accent-100);
989
+ --color-accent: var(--cg-ui-color-accent);
990
+ --color-accent-subtle: var(--cg-ui-color-accent-subtle);
912
991
  }
913
992
  ```
914
993
 
915
- 3. **Document in README** (this file)
994
+ 5. **Document in README** (this file)
916
995
 
917
- 4. **Use in components**
996
+ 6. **Use in components**
918
997
 
919
998
  ```svelte
999
+ <!-- Via Tailwind classes (recommended) -->
1000
+ <div class="bg-accent text-accent-subtle">...</div>
1001
+
1002
+ <!-- Or via CSS variables directly -->
920
1003
  <style>
921
1004
  .my-component {
922
- background-color: var(--color-accent);
1005
+ background-color: var(--cg-ui-color-accent);
923
1006
  }
924
1007
  </style>
925
1008
  ```