@demos-europe/demosplan-ui 0.3.19 → 0.3.21

package/tokens/src/color/color.ui.json

@@ -7,32 +7,38 @@
         "default": {
           "$description": "Default state.",
           "value": "{color.palette.blue.base}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "hover": {
           "$description": "Hover state.",
           "value": "{color.palette.blue.dark-1}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "subtle-hover": {
           "$description": "Use as background to visualize hover state for bigger areas or buttons.",
           "value": "{color.palette.neutral.light-4}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "subtle-active": {
           "$description": "Use as background to visualize active state for bigger areas or buttons.",
           "value": "{color.palette.neutral.light-3}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "active": {
           "$description": "Active/pressed state.",
           "value": "{color.palette.blue.dark-2}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "muted": {
           "$description": "Use for interactive elements that reveal their base state on:hover of a parent element, eg. in a table row. Note that this is not to be conflated with the disabled state, which is communicated via opacity.",
           "value": "{color.palette.neutral.light-1}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         }
       },
       "message": {
@@ -41,115 +47,140 @@
           "$description": "Use these colors to communicate uncritical information.",
           "bg": {
             "value": "{color.palette.blue.light-3}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "border": {
             "value": "{color.palette.blue.light-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "fill": {
             "value": "{color.palette.blue.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "interactive": {
             "value": "{color.palette.blue.base}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.blue.dark-2}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         },
         "warning": {
           "$description": "Use these colors to noticeably communicate uncritical information.",
           "bg": {
             "value": "{color.palette.yellow.light-3}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "border": {
             "value": "{color.palette.yellow.base}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "fill": {
             "value": "{color.palette.yellow.dark-2}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "interactive": {
             "value": "{color.palette.yellow.dark-2}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.yellow.dark-2}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         },
         "severe": {
           "$description": "Use these colors to communicate importance, danger, and immediate action.",
           "bg": {
             "value": "{color.palette.red.light-3}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "border": {
             "value": "{color.palette.red.light-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "fill": {
             "value": "{color.palette.red.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "interactive": {
             "value": "{color.palette.red.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.red.dark-2}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         },
         "success": {
           "$description": "Use these colors to communicate successful state change.",
           "bg": {
             "value": "{color.palette.green.light-3}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "border": {
             "value": "{color.palette.green.light-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "fill": {
             "value": "{color.palette.green.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "interactive": {
             "value": "{color.palette.green.base}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.green.dark-2}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         },
         "debug": {
           "$description": "Use these colors to communicate information for debugging purposes.",
           "bg": {
             "value": "{color.palette.purple.light-3}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "border": {
             "value": "{color.palette.purple.light-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "fill": {
             "value": "{color.palette.purple.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "interactive": {
             "value": "{color.palette.purple.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.purple.dark-2}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         }
       },
@@ -159,59 +190,70 @@
           "$description": "Use these colors to communicate that something is in progress",
           "fill": {
             "value": "{color.palette.blue.base}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.blue.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         },
         "changed": {
           "$description": "Use these colors to communicate something has moved or changed.",
           "fill": {
             "value": "{color.palette.yellow.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.yellow.dark-2}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         },
         "failed": {
           "$description": "Use these colors to communicate that an action or validation has failed on an item.",
           "border": {
             "value": "{color.palette.red.base}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "fill": {
             "value": "{color.palette.red.base}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.red.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         },
         "complete": {
           "$description": "Use these colors to communicate that an action has completed, or something has been added.",
           "fill": {
             "value": "{color.palette.green.base}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.green.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         },
         "neutral": {
           "$description": "Use these colors if no other option applies.",
           "fill": {
             "value": "{color.palette.neutral.base}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           },
           "text": {
             "value": "{color.palette.neutral.dark-1}",
-            "themeable": true
+            "themeable": true,
+            "$type": "color"
           }
         }
       },
@@ -220,59 +262,71 @@
         "default": {
           "$description": "Default color for text that should be readable.",
           "value": "{color.palette.neutral.dark-2}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "muted": {
           "$description": "Default color for text that should stand out a little less. Has sufficient contrast on white.",
           "value": "{color.palette.neutral.base}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "on-dark": {
           "$description": "Default color for text that has sufficient contrast on dark backgrounds.",
           "value": "{color.palette.white}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "marked": {
           "$description": "Color for highlighting portions of text.",
           "value": "{color.palette.blue.dark-2}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "marked-bg": {
           "$description": "Background color for highlighting portions of text.",
           "value": "{color.palette.blue.light-3}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "inserted-bg": {
           "$description": "Background color for inserted (ins) text.",
           "value": "{color.palette.blue.light-3}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "inserted-bg-muted": {
           "$description": "Background color for highlighting portions of text, that is discernible from 'marked-bg'",
           "value": "{color.palette.blue.light-4}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "deleted-bg": {
           "$description": "Background color for deleted (del) text.",
           "value": "{color.palette.yellow.light-2}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "deleted-bg-muted": {
           "$description": "Background color for deleted (del) text.",
           "value": "{color.palette.yellow.light-3}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         }
       },
       "selection": {
-        "$description": "Color used to visualize selected elements.",
         "$status": "{_status.review}",
         "text": {
+          "$description": "Color used to visualize selected elements.",
           "value": "{color.palette.blue.dark-1}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "bg": {
+          "$description": "Background Color used to visualize selected elements.",
           "value": "{color.palette.blue.light-3}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         }
       },
       "border": {
@@ -286,17 +340,20 @@
         "default": {
           "$description": "Default color used for backgrounds.",
           "value": "{color.palette.white}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "light": {
           "$description": "Lightest background color that is discernible on normal monitors.",
           "value": "{color.palette.neutral.light-4}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         },
         "medium": {
           "$description": "Medium background color for boxes etc.",
           "value": "{color.palette.neutral.light-3}",
-          "themeable": true
+          "themeable": true,
+          "$type": "color"
         }
       }
     }

package/tokens/tokens.color.stories.mdx

@@ -1,4 +1,7 @@
 import { Meta } from '@storybook/addon-docs'
+import ColorTableGrouped from '../.storybook/components/ColorTableGrouped'
+import ColorTable from '../.storybook/components/ColorTable'
+import Notice from '../.storybook/components/Notice'
 
 <Meta title="Design Tokens/Color"/>
 
@@ -10,13 +13,57 @@ import { Meta } from '@storybook/addon-docs'
 
 # Color tokens
 
-The demosplan-ui color tokens are grouped into *palette* (the raw values which should not be used directly), *brand* (for
-colors used in branded context), *message* and *status* (to communicate system state), *data* (for data visualization)
-and *interaction* (to indicate interaction). Apart from *brand*, colors are not meant to be themeable.
+The demosplan-ui color tokens are grouped into <a target="_self" href="#brand-colors">**brand**</a> (for colors used in branded context),
+<a target="_self" href="#data-visualization-colors">**data**</a> (for data visualization) and
+<a target="_self" href="#functional-semantic-color-tokens">**semantic tokens**</a> for visualizing **message**, **status**
+(to communicate system state) and **interactive** (to indicate possible interaction), alongside tokens for **text**, **surface**,
+and **border** colors used throughout the interface. A full list of all palette colors (the raw color values which cannot
+be used directly) can be found <a target="_self" href="#palette-colors">here</a>.
+
+Tokens are available as <a target="_self" href="#tailwind-utility-classes">Tailwind utility classes</a> and <a target="_self" href="#scss-variables">SCSS variables</a>.
+
+<Notice content={
+  `Note that the naming scheme for ui colors differs between Tailwind and SCSS, as SCSS follows a legacy naming scheme,
+   while Tailwind enforces the property name or short name as the first part of the selector.`
+} />
 
 ## How to use and override color tokens
 
-Color tokens can be consumed as Scss variables. To use them, they have to be imported at first:
+### Tailwind utility classes
+
+To use tokens via Tailwind utility classes, the `tailwind.config.js` provided by demosplan-ui
+must be merged into the config of the consuming application:
+
+```
+const config = {
+  ...require('@demos-europe/demosplan-ui/tailwind.config'),
+  content: [ // Files to watch for tailwind classes ],
+  // Other config values
+}
+
+module.exports = config
+```
+
+Then, they can be applied to markup that is matched in the `content` definition.
+
+#### Overriding Tailwind colors
+
+Tailwind classes are defined to use a cascade of CSS variables. Each selector that inherits from a variable
+will also be overridden. This way, it is possible to globally override colors, or to override a specific variable:
+
+```
+:root {
+    // Globally override a palette color
+    --dp-color-blue-base: #2400d0;
+
+    // Override a specific variable
+    --dp-color-interactive-hover: #e100bd;
+}
+```
+
+### SCSS Variables
+
+To use tokens via SCSS variables, they have to be imported at first:
 
 ```
 @import '@demos-europe/demosplan-ui/tokens/scss/color.palette';
@@ -39,8 +86,9 @@ Then, tokens can be used within Scss code:
 }
 ```
 
-To override the value of a specific token, define the override
-before importing the provided file:
+#### Overriding SCSS Variables
+
+To override the value of a specific token, define the override before importing the provided file:
 
 ```
 // Set a new color for just this one token:
@@ -55,7 +103,7 @@ $dp-color-interactive-hover: #9700ff;
 
 If you want to override tokens with other token values, you
 would have to import those first. Also, by importing alias
-tokens afterwards, they are as well assigned the changed values.
+tokens afterward, they are as well assigned the changed values.
 
 ```
 @import '@demos-europe/demosplan-ui/tokens/scss/color.palette';
@@ -74,48 +122,38 @@ $dp-color-main: $dp-color-yellow-base;
 // Use tokens...
 ```
 
-## Available tokens
-
-### Palette colors
+## Available color tokens
 
-Color palettes resemble all colors available within demosplan-ui. Available color palettes contain 7 steps:
-a base color, 2 shades and 4 lights. The colors are complemented with white, black, and neutral.
+**brand**, **data** and **interactive** colors are enabled for all Tailwind corePlugins that apply color.
+A full list of those corePlugins can be found [in the config.full.js stub for tailwind](https://github.com/tailwindlabs/tailwindcss/blob/master/stubs/config.full.js) - each plugin that applies `theme('colors')`.
 
-### Brand colors
+**backgroundColor**, **borderColor** and **textColor** corePlugins each define additional available ui colors.
 
-For contexts that require to express brand, the *main*, *alt*, and *highlight* tokens exist. Like message, status,
-and interaction tokens, they are aliased to palette tokens.
+### Functional (semantic) color tokens
 
-### Functional (UI) colors
+When building UI with a focus on functionality, not brand, the following semantic tokens can be used.
 
-When building UI with a focus on functionality, not brand, the *interactive*, *message*, and *status* tokens can be utilized.
+#### Tokens available for all corePlugins
 
-#### Interactive
+<ColorTableGrouped module={'color'} />
 
-Be it links, buttons, or other elements users can interact with: whenever an interface element should convey
-its interactive nature, the *interactive* tokens can be used.
+#### Text colors
 
-#### Message
+<ColorTableGrouped module={'textColor'} />
 
-Message color is used to communicate system feedback. For each group, the following tokens exist:
+#### Background colors
 
-- `-bg` Background color
-- `-border` Border color
-- `-interactive` Color for links and other interactive elements
-- `-fill` Fill color for icons or other svg
-- `-text` Text color
+<ColorTableGrouped module={'backgroundColor'} />
 
-#### Status
+#### Border colors
 
-System state is typically communicated via icons (maybe in condensed table rows) or as colored text. For these cases,
-the following *status* tokens can be used:
+<ColorTableGrouped module={'borderColor'} />
 
-- `-fill` Fill color for icons or other svg
-- `-text` Text color
+### Brand colors
 
-The tokens are to be used for elements on a white background.
+For contexts that require to express brand, the *main*, *alt*, and *highlight* tokens exist.
 
-**More ui tokens are still to be documented.**
+<ColorTable namespace={'brand'} />
 
 ### Data visualization colors
 
@@ -125,6 +163,8 @@ that differentiate from each other. Like palette colors, they contain hex values
 These are generated with https://colorbrewer2.org/#type=diverging&scheme=BrBG&n=8 to be colorblind safe
 and intentionally separate from other color palettes.
 
+<ColorTable namespace={'data'} />
+
 Although these colors are universally used for charts, they need to be refined into "sequential", "categorical",
 and "diverging" when appropriate. Read more if the need arises:
 
@@ -133,3 +173,12 @@ and "diverging" when appropriate. Read more if the need arises:
 - https://medium.com/design-ibm/inclusive-color-sequences-for-data-viz-in-6-steps-712869b910c2
 - https://medium.com/carbondesign/color-palettes-and-accessibility-features-for-data-visualization-7869f4874fca
 - https://blog.graphiq.com/finding-the-right-color-palettes-for-data-visualizations-fcd4e707a283
+
+### Palette colors
+
+Color palettes resemble all colors available within demosplan-ui. Available color palettes contain 7 steps:
+a base color, 2 shades and 4 lights. The colors are complemented with white, black, and neutral.
+
+<Notice content={'Palette colors are not meant nor made to be used directly - instead, the functional colors defined above should be utilized.'} />
+
+<ColorTable namespace={'palette'} />

package/tokens/tokens.space.stories.mdx

@@ -30,25 +30,25 @@ Spacing tokens define the spacing scale available with demosplan-ui.
   ]}
 />
 
-<ul className="list-none space-y-2 shadow p-2 inline-block">
-  <li className="w-0 bg-blue-500">0</li>
-  <li className="w-px bg-blue-500">px</li>
-  <li className="w-0.5 bg-blue-500">0.5</li>
-  <li className="w-1 bg-blue-500">1</li>
-  <li className="w-1.5 bg-blue-500">1.5</li>
-  <li className="w-2 bg-blue-500">2</li>
-  <li className="w-3 bg-blue-500">3</li>
-  <li className="w-4 bg-blue-500">4</li>
-  <li className="w-5 bg-blue-500">5</li>
-  <li className="w-6 bg-blue-500">6</li>
-  <li className="w-7 bg-blue-500">7</li>
-  <li className="w-8 bg-blue-500">8</li>
-  <li className="w-9 bg-blue-500">9</li>
-  <li className="w-10 bg-blue-500">10</li>
-  <li className="w-11 bg-blue-500">11</li>
-  <li className="w-12 bg-blue-500">12</li>
-  <li className="w-13 bg-blue-500">13</li>
-  <li className="w-14 bg-blue-500">14</li>
+<ul className="sb-unstyled list-none space-y-2 shadow p-2 inline-block">
+  <li className="w-0 bg-message-debug">0</li>
+  <li className="w-px bg-message-debug">px</li>
+  <li className="w-0.5 bg-message-debug">0.5</li>
+  <li className="w-1 bg-message-debug">1</li>
+  <li className="w-1.5 bg-message-debug">1.5</li>
+  <li className="w-2 bg-message-debug">2</li>
+  <li className="w-3 bg-message-debug">3</li>
+  <li className="w-4 bg-message-debug">4</li>
+  <li className="w-5 bg-message-debug">5</li>
+  <li className="w-6 bg-message-debug">6</li>
+  <li className="w-7 bg-message-debug">7</li>
+  <li className="w-8 bg-message-debug">8</li>
+  <li className="w-9 bg-message-debug">9</li>
+  <li className="w-10 bg-message-debug">10</li>
+  <li className="w-11 bg-message-debug">11</li>
+  <li className="w-12 bg-message-debug">12</li>
+  <li className="w-13 bg-message-debug">13</li>
+  <li className="w-14 bg-message-debug">14</li>
 </ul>
 
 While the values `0.5` to `6` follow a linear progression with "in-betweens",
@@ -79,6 +79,6 @@ They replace the default classes mentioned in the [Tailwind documentation](https
 Instead, the custom spacing scale shown here is inherited by the padding, margin, width, height, maxHeight,
 gap, inset, space, translate, scrollMargin, and scrollPadding core plugins of Tailwind.
 
-<div className="w-6 h-6 space-y-2 gap-1.5 bg-blue-500">
+<div className="w-6 h-6 space-y-2 gap-1.5 bg-message-debug">
   Css is awesome.
 </div>