@cumulus-ui/design-tokens 0.1.0 → 0.3.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 +117 -0
  2. package/index.d.ts +253 -0
  3. package/index.js +690 -437
  4. package/package.json +1 -1
  5. package/tokens.css +1047 -735
package/README.md ADDED
@@ -0,0 +1,117 @@
1
+ # @cumulus-ui/design-tokens
2
+
3
+ CSS custom properties for Cumulus UI — light and dark mode tokens generated from Cloudscape Design System.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @cumulus-ui/design-tokens
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ ### CSS
14
+
15
+ Load the token stylesheet once in your application entry point:
16
+
17
+ ```js
18
+ import '@cumulus-ui/design-tokens/tokens.css';
19
+ ```
20
+
21
+ Then use tokens as CSS custom properties anywhere:
22
+
23
+ ```css
24
+ .my-component {
25
+ color: var(--color-text-body-default);
26
+ background: var(--color-background-layout-main);
27
+ border-radius: var(--border-radius-container);
28
+ }
29
+ ```
30
+
31
+ ### JavaScript / TypeScript
32
+
33
+ For inline styles or JS-driven styling, import named token constants:
34
+
35
+ ```js
36
+ import { colorTextBodyDefault, colorBackgroundLayoutMain } from '@cumulus-ui/design-tokens';
37
+
38
+ element.style.color = colorTextBodyDefault; // → "var(--color-text-body-default)"
39
+ ```
40
+
41
+ ### Dark mode
42
+
43
+ Tokens respond to the `.awsui-dark-mode` class on `<html>`:
44
+
45
+ ```js
46
+ // Enable dark mode
47
+ document.documentElement.classList.add('awsui-dark-mode');
48
+
49
+ // Disable dark mode
50
+ document.documentElement.classList.remove('awsui-dark-mode');
51
+ ```
52
+
53
+ All token values update automatically — no additional imports or class changes needed.
54
+
55
+ ## Token naming
56
+
57
+ Tokens follow the Cloudscape [CTI naming convention](https://cloudscape.design/foundation/visual-foundation/design-tokens/) (Category → Type → Item → State):
58
+
59
+ ```
60
+ --color-background-button-primary-default
61
+ │ │ │ │ └─ state
62
+ │ │ │ └───────── sub-item
63
+ │ │ └───────────────── item
64
+ │ └─────────────────────────── type
65
+ └─────────────────────────────────── category
66
+ ```
67
+
68
+ ## Design decisions
69
+
70
+ ### No hashed variable names
71
+
72
+ Cloudscape uses content-hashed suffixes on CSS custom property names (e.g. `--color-text-body-default-vvtq8u`). The hash is an MD5 digest of the token's value set, designed to signal version changes and discourage direct CSS usage in their React ecosystem.
73
+
74
+ Cumulus strips these hashes. Our CSS properties use canonical token names directly:
75
+
76
+ ```css
77
+ /* Cloudscape */
78
+ var(--color-text-body-default-vvtq8u, #0f141a)
79
+
80
+ /* Cumulus */
81
+ var(--color-text-body-default, #0f141a)
82
+ ```
83
+
84
+ **Why:** Hashed names provide collision avoidance and version signaling, but at the cost of developer experience. Every other web component design system (Shoelace, Spectrum, Carbon, Vaadin) uses clean, human-readable names. Since Cumulus owns both the token definitions and the component CSS, we can guarantee name-value consistency through our generation pipeline rather than encoding it in variable names. See the full rationale below.
85
+
86
+ **What Cloudscape's hashes solve and how we address each:**
87
+
88
+ | Cloudscape concern | Hash solution | Cumulus alternative |
89
+ |---|---|---|
90
+ | Value changes break silently | Hash changes → loud CSS failure | We regenerate tokens + components in the same release |
91
+ | Direct CSS usage discouraged | Names are unmemorable | Direct CSS usage is encouraged — clean names are the API |
92
+ | Multi-theme collision | Different hashes per theme | Not applicable; single-theme with light/dark mode |
93
+
94
+ ### No namespace prefix
95
+
96
+ Unlike other design systems (`--sl-`, `--cds-`, `--spectrum-`), Cumulus tokens have no prefix. The CTI naming convention produces specific enough names (`--color-background-button-primary-default`) that collisions are impractical. If a prefix becomes necessary (e.g. for multi-system pages), it can be added to the generator with a one-line change.
97
+
98
+ ### No fallbacks in JS exports
99
+
100
+ The JavaScript token exports contain `var()` references without fallback values:
101
+
102
+ ```js
103
+ export const colorTextBodyDefault = "var(--color-text-body-default)";
104
+ // NOT: "var(--color-text-body-default, #0f141a)"
105
+ ```
106
+
107
+ This is intentional. If `tokens.css` is not loaded, things should break visibly rather than silently rendering light-mode-only values. Component CSS retains inline fallbacks as a safety net for Shadow DOM isolation.
108
+
109
+ ## Regenerating
110
+
111
+ Tokens are auto-generated from `@cloudscape-design/design-tokens`:
112
+
113
+ ```bash
114
+ npm run generate
115
+ ```
116
+
117
+ This reads the upstream JSON (token names + light/dark values) and JS (to discover the token set), then outputs `tokens.css`, `index.js`, and `index.d.ts` with clean names.
package/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  // AUTO-GENERATED from @cloudscape-design/design-tokens — DO NOT EDIT
2
+ // License: see /NOTICE
2
3
  export declare const colorChartsRed300: string;
3
4
  export declare const colorChartsRed400: string;
4
5
  export declare const colorChartsRed500: string;
@@ -436,3 +437,255 @@ export declare const spaceStaticXxl: string;
436
437
  export declare const spaceStaticXxxl: string;
437
438
  export declare const shadowCard: string;
438
439
  export declare const shadowContainerActive: string;
440
+ export declare const motionDurationShowPaced: string;
441
+ export declare const motionEasingShowPaced: string;
442
+ export declare const spaceAlertHorizontal: string;
443
+ export declare const spaceAlertActionLeft: string;
444
+ export declare const spaceButtonFocusOutlineGutter: string;
445
+ export declare const spaceXxs: string;
446
+ export declare const spaceAlertMessageRight: string;
447
+ export declare const sizeIconMedium: string;
448
+ export declare const spaceXs: string;
449
+ export declare const sizeIconBig: string;
450
+ export declare const sizeIconNormal: string;
451
+ export declare const spaceS: string;
452
+ export declare const motionDurationSlow: string;
453
+ export declare const borderLinkFocusRingOutline: string;
454
+ export declare const borderLinkFocusRingShadowSpread: string;
455
+ export declare const fontWayfindingLinkActiveWeight: string;
456
+ export declare const fontSmoothingWebkit: string;
457
+ export declare const fontSmoothingMozOsx: string;
458
+ export declare const letterSpacingBodyS: string;
459
+ export declare const spaceContentHeaderPaddingBottom: string;
460
+ export declare const spaceLayoutContentBottom: string;
461
+ export declare const spaceDarkHeaderOverlapDistance: string;
462
+ export declare const motionDurationTransitionShowPaced: string;
463
+ export declare const motionEasingTransitionShowPaced: string;
464
+ export declare const spaceGridGutter: string;
465
+ export declare const borderDividerSectionWidth: string;
466
+ export declare const motionDurationRefreshOnlyMedium: string;
467
+ export declare const colorTextSmall: string;
468
+ export declare const fontDisplayLabelWeight: string;
469
+ export declare const spaceKeyValueGap: string;
470
+ export declare const fontBoxValueLargeWeight: string;
471
+ export declare const colorBackgroundInlineCode: string;
472
+ export declare const fontWeightHeavy: string;
473
+ export declare const spaceScaledNone: string;
474
+ export declare const spaceNone: string;
475
+ export declare const spaceXxxs: string;
476
+ export declare const spaceM: string;
477
+ export declare const spaceL: string;
478
+ export declare const spaceXl: string;
479
+ export declare const spaceXxl: string;
480
+ export declare const spaceXxxl: string;
481
+ export declare const fontButtonLetterSpacing: string;
482
+ export declare const spaceButtonHorizontal: string;
483
+ export declare const colorTextButtonInlineIconDefault: string;
484
+ export declare const colorTextButtonInlineIconHover: string;
485
+ export declare const colorTextButtonInlineIconDisabled: string;
486
+ export declare const spaceButtonIconFocusOutlineGutterVertical: string;
487
+ export declare const spaceButtonInlineIconFocusOutlineGutter: string;
488
+ export declare const spaceButtonIconOnlyHorizontal: string;
489
+ export declare const spaceButtonModalDismissVertical: string;
490
+ export declare const motionEasingShowQuick: string;
491
+ export declare const colorBorderDropdownGroup: string;
492
+ export declare const motionDurationShowQuick: string;
493
+ export declare const sizeCalendarGridWidth: string;
494
+ export declare const spaceCalendarGridGutter: string;
495
+ export declare const colorTextCalendarMonth: string;
496
+ export declare const colorBorderCalendarGrid: string;
497
+ export declare const colorTextDropdownItemSecondary: string;
498
+ export declare const colorTextCalendarDateHover: string;
499
+ export declare const borderItemWidth: string;
500
+ export declare const colorBackgroundCalendarCurrentDate: string;
501
+ export declare const spaceCalendarGridFocusOutlineGutter: string;
502
+ export declare const colorBorderCalendarGridSelectedFocusRing: string;
503
+ export declare const spaceContainerHeaderBottom: string;
504
+ export declare const spaceTableHeaderToolsFullPageBottom: string;
505
+ export declare const sizeControl: string;
506
+ export declare const borderRadiusCodeEditor: string;
507
+ export declare const colorBorderCodeEditorAceActiveLineLightTheme: string;
508
+ export declare const colorBorderCodeEditorAceActiveLineDarkTheme: string;
509
+ export declare const colorBackgroundCodeEditorGutterDefault: string;
510
+ export declare const colorTextCodeEditorGutterDefault: string;
511
+ export declare const colorBackgroundCodeEditorGutterActiveLineDefault: string;
512
+ export declare const colorTextCodeEditorGutterActiveLine: string;
513
+ export declare const colorBackgroundCodeEditorGutterActiveLineError: string;
514
+ export declare const colorBorderCodeEditorDefault: string;
515
+ export declare const colorBackgroundCodeEditorStatusBar: string;
516
+ export declare const colorTransparent: string;
517
+ export declare const colorBackgroundCodeEditorPaneItemHover: string;
518
+ export declare const colorBorderCodeEditorPaneItemHover: string;
519
+ export declare const colorTextCodeEditorTabButtonError: string;
520
+ export declare const borderActiveWidth: string;
521
+ export declare const motionEasingRefreshOnlyC: string;
522
+ export declare const colorTextCodeEditorStatusBarDisabled: string;
523
+ export declare const spaceCodeEditorStatusFocusOutlineGutter: string;
524
+ export declare const borderCodeEditorStatusDividerWidth: string;
525
+ export declare const colorBorderTabsDivider: string;
526
+ export declare const colorBackgroundCodeEditorLoading: string;
527
+ export declare const colorTextFormLabel: string;
528
+ export declare const borderDividerListWidth: string;
529
+ export declare const borderContainerTopWidth: string;
530
+ export declare const shadowContainer: string;
531
+ export declare const shadowStickyEmbedded: string;
532
+ export declare const borderContainerStickyWidth: string;
533
+ export declare const colorBorderContainerDivider: string;
534
+ export declare const spaceContainerHeaderTop: string;
535
+ export declare const shadowSticky: string;
536
+ export declare const spaceContainerContentTop: string;
537
+ export declare const spaceLayoutContentHorizontal: string;
538
+ export declare const colorBorderDropdownItemDefault: string;
539
+ export declare const fontPanelHeaderSize: string;
540
+ export declare const fontPanelHeaderLineHeight: string;
541
+ export declare const spacePanelHeaderVertical: string;
542
+ export declare const spacePanelSideLeft: string;
543
+ export declare const colorBorderPanelHeader: string;
544
+ export declare const spacePanelContentTop: string;
545
+ export declare const spacePanelSideRight: string;
546
+ export declare const spacePanelContentBottom: string;
547
+ export declare const colorTextExpandableSectionDefault: string;
548
+ export declare const fontExpandableHeadingSize: string;
549
+ export declare const spaceExpandableSectionIconOffsetTop: string;
550
+ export declare const colorTextExpandableSectionNavigationIconDefault: string;
551
+ export declare const colorTextExpandableSectionHover: string;
552
+ export declare const borderControlFocusRingShadowSpread: string;
553
+ export declare const borderInvalidWidth: string;
554
+ export declare const colorBorderInputDisabled: string;
555
+ export declare const colorBorderControlDisabled: string;
556
+ export declare const shadowFlashCollapsed: string;
557
+ export declare const colorBackgroundNotificationStackBar: string;
558
+ export declare const colorBorderNotificationStackBar: string;
559
+ export declare const shadowPanelToggle: string;
560
+ export declare const colorTextNotificationStackBar: string;
561
+ export declare const colorBackgroundNotificationStackBarHover: string;
562
+ export declare const colorBackgroundNotificationStackBarActive: string;
563
+ export declare const spaceFlashbarVertical: string;
564
+ export declare const spaceFlashbarHorizontal: string;
565
+ export declare const shadowFlashSticky: string;
566
+ export declare const spaceFlashbarActionLeft: string;
567
+ export declare const spaceFlashbarDismissRight: string;
568
+ export declare const colorTextNotificationYellow: string;
569
+ export declare const motionEasingRefreshOnlyA: string;
570
+ export declare const spaceScaled2xXxs: string;
571
+ export declare const sizeVerticalInput: string;
572
+ export declare const fontHeaderH2DescriptionSize: string;
573
+ export declare const fontHeaderH2DescriptionLineHeight: string;
574
+ export declare const spacePanelDividerMarginHorizontal: string;
575
+ export declare const sizeIconLarge: string;
576
+ export declare const colorTextInverted: string;
577
+ export declare const colorTextIconSubtle: string;
578
+ export declare const colorBackgroundBadgeIcon: string;
579
+ export declare const colorTextInputPlaceholderDisabled: string;
580
+ export declare const borderControlInvalidFocusRingShadowSpread: string;
581
+ export declare const spaceFieldIconOffset: string;
582
+ export declare const colorBackgroundItemCard: string;
583
+ export declare const shadowItemCard: string;
584
+ export declare const borderWidthItemCard: string;
585
+ export declare const colorBorderItemCard: string;
586
+ export declare const borderWidthItemCardHighlighted: string;
587
+ export declare const colorBorderItemCardHighlighted: string;
588
+ export declare const borderRadiusItemCardEmbedded: string;
589
+ export declare const spaceItemCardVerticalEmbedded: string;
590
+ export declare const spaceItemCardHorizontalEmbedded: string;
591
+ export declare const borderRadiusItemCardDefault: string;
592
+ export declare const spaceItemCardVerticalDefault: string;
593
+ export declare const spaceItemCardHorizontalDefault: string;
594
+ export declare const colorTextLinkButtonUnderlineHover: string;
595
+ export declare const fontLinkButtonWeight: string;
596
+ export declare const fontLinkButtonLetterSpacing: string;
597
+ export declare const colorTextLinkButtonUnderline: string;
598
+ export declare const colorTextLinkButtonNormalDefault: string;
599
+ export declare const colorTextLinkButtonNormalHover: string;
600
+ export declare const colorTextLinkButtonNormalActive: string;
601
+ export declare const colorTextLinkInvertedHover: string;
602
+ export declare const motionDurationFast: string;
603
+ export declare const motionDurationRefreshOnlyFast: string;
604
+ export declare const motionDurationExtraSlow: string;
605
+ export declare const colorBackgroundModalOverlay: string;
606
+ export declare const shadowModal: string;
607
+ export declare const spaceModalContentBottom: string;
608
+ export declare const spaceModalHorizontal: string;
609
+ export declare const colorTextPaginationPageNumberDefault: string;
610
+ export declare const colorTextPaginationPageNumberActiveDisabled: string;
611
+ export declare const colorShadowDefault: string;
612
+ export declare const shadowPopover: string;
613
+ export declare const motionDurationModerate: string;
614
+ export declare const colorTextDropdownGroupLabel: string;
615
+ export declare const colorTextColumnHeader: string;
616
+ export declare const spaceSegmentedControlFocusOutlineGutter: string;
617
+ export declare const colorBackgroundSegmentWrapper: string;
618
+ export declare const spacePanelNavLeft: string;
619
+ export declare const spaceScaled2xL: string;
620
+ export declare const spaceScaled2xM: string;
621
+ export declare const spaceScaled2xXl: string;
622
+ export declare const colorBackgroundSliderRangeErrorDefault: string;
623
+ export declare const colorBackgroundSliderRangeWarningDefault: string;
624
+ export declare const colorBackgroundSliderRangeErrorActive: string;
625
+ export declare const colorBackgroundSliderRangeWarningActive: string;
626
+ export declare const colorBackgroundSliderHandleRing: string;
627
+ export declare const colorBackgroundSliderHandleErrorDefault: string;
628
+ export declare const colorBackgroundSliderHandleErrorActive: string;
629
+ export declare const colorBackgroundSliderHandleWarningDefault: string;
630
+ export declare const colorBackgroundSliderHandleWarningActive: string;
631
+ export declare const colorBackgroundLayoutPanelContent: string;
632
+ export declare const colorBackgroundLayoutPanelHover: string;
633
+ export declare const borderPanelTopWidth: string;
634
+ export declare const colorBorderDividerPanelBottom: string;
635
+ export declare const shadowSplitBottom: string;
636
+ export declare const shadowSplitSide: string;
637
+ export declare const borderPanelHeaderWidth: string;
638
+ export declare const spacePanelSplitTop: string;
639
+ export declare const spaceLayoutToggleDiameter: string;
640
+ export declare const spaceLayoutTogglePadding: string;
641
+ export declare const spacePanelSplitBottom: string;
642
+ export declare const sizeVerticalPanelIconOffset: string;
643
+ export declare const spaceTableHeaderToolsBottom: string;
644
+ export declare const spaceTableHorizontal: string;
645
+ export declare const spaceTableContentBottom: string;
646
+ export declare const sizeTableSelectionHorizontal: string;
647
+ export declare const colorBackgroundTableHeader: string;
648
+ export declare const spaceTableHeaderHorizontal: string;
649
+ export declare const spaceTableEmbeddedHeaderTop: string;
650
+ export declare const spaceTableFooterHorizontal: string;
651
+ export declare const colorBorderTabsShadow: string;
652
+ export declare const colorBorderTabsUnderline: string;
653
+ export declare const fontTabsSize: string;
654
+ export declare const fontTabsLineHeight: string;
655
+ export declare const spaceTabsFocusOutlineGutter: string;
656
+ export declare const fontTabsDisabledWeight: string;
657
+ export declare const spaceTabsContentTop: string;
658
+ export declare const motionDurationTransitionQuick: string;
659
+ export declare const motionEasingTransitionQuick: string;
660
+ export declare const colorBorderTilesDisabled: string;
661
+ export declare const colorBackgroundTilesDisabled: string;
662
+ export declare const spaceTileGutter: string;
663
+ export declare const colorBackgroundToggleDefault: string;
664
+ export declare const motionEasingEaseOutQuart: string;
665
+ export declare const colorTextDisabled: string;
666
+ export declare const colorBorderLayout: string;
667
+ export declare const spaceScaled2xXxxl: string;
668
+ export declare const colorNeutral600: string;
669
+ export declare const colorNeutral450: string;
670
+ export declare const colorNeutral200: string;
671
+ export declare const colorNeutral700: string;
672
+ export declare const colorNeutral100: string;
673
+ export declare const colorNeutral850: string;
674
+ export declare const colorNeutral300: string;
675
+ export declare const colorNeutral800: string;
676
+ export declare const colorNeutral950: string;
677
+ export declare const colorNeutral500: string;
678
+ export declare const colorWhite: string;
679
+ export declare const colorNeutral250: string;
680
+ export declare const colorNeutral350: string;
681
+ export declare const colorNeutral650: string;
682
+ export declare const colorNeutral750: string;
683
+ export declare const colorNeutral400: string;
684
+ export declare const colorError600: string;
685
+ export declare const colorError400: string;
686
+ export declare const borderWidthCardHighlighted: string;
687
+ export declare const colorBorderCardHighlighted: string;
688
+ export declare const colorGreyOpaque70: string;
689
+ export declare const shadowDropdown: string;
690
+ export declare const colorGreyTransparentHeavy: string;
691
+ export declare const colorGreyTransparent: string;