Introduce color dictionaries for generative styling of components

mkdocs.yml

@@ -84,6 +84,7 @@ nav:
           - 'Browsers & Devices': 'docs/getting-started/browsers-and-devices.md'
       - Foundation:
           - 'Design Tokens': 'docs/foundation/design-tokens.md'
+          - 'Dictionaries': 'docs/foundation/dictionaries.md'
           - 'Colors': 'docs/foundation/colors.md'
           - 'Typography': 'docs/foundation/typography.md'
           - 'Spacing': 'docs/foundation/spacing.md'

src/docs/foundation/colors.md

@@ -234,16 +234,9 @@ Components can apply colors above using one or more following color groups.
 Some components ([Alert](/components/Alert), [Badge](/components/Badge),
 [Button](/components/Button), and more) come in more color variants to help you
 better reflect their place in content hierarchy or the meaning of their content.
-Following colors are available in such cases:
-
-- **action colors (actionable components only):** `primary`, `secondary`, and
-  `selected`,
-- **feedback colors:** `success`, `warning`, `danger`, `help`, `info`, and
-  `note`,
-- **neutral colors:** `light` and `dark`.
-
-There is always a reasonable default for the component in question that can be
-changed to any of supported values above through the `color` prop.
+In such cases, one or more [Color Dictionaries][dictionary-colors] are always used.
+There is always a reasonable default color for the component in question that can
+be changed to any of supported dictionary values through the `color` prop.
 
 ### Validation States
 
@@ -258,3 +251,5 @@ apply selected [feedback colors](#feedback-colors) for individual states:
 
 Validation state is always optional. Default styling is applied for the given
 component when its `validationState` prop is not specified.
+
+[dictionary-colors]: /docs/foundation/dictionaries#colors

src/docs/foundation/dictionaries.md

@@ -0,0 +1,20 @@
+# Dictionaries
+
+Dictionaries are collections of predefined values that can be used in various
+components. They are useful for ensuring consistency and reducing the likelihood
+of errors.
+
+## Colors
+
+The following color names are designed for use in components that support the
+`color` prop:
+
+| Category | Available values                                       |
+|----------|--------------------------------------------------------|
+| Action   | `primary`, `secondary`, `selected`                     |
+| Feedback | `success`, `warning`, `danger`, `info`, `help`, `note` |
+| Neutral  | `light`, `dark`                                        |
+
+Not all dictionaries are available in all components with the `color` prop.
+Refer to the documentation for each component to see which dictionaries are
+available.

src/styles/settings/_dictionaries.scss

@@ -0,0 +1,9 @@
+$action-colors: primary, secondary, selected;
+$feedback-colors: success, warning, danger, info, help, note;
+$neutral-colors: light, dark;
+
+$colors: (
+    action: $action-colors,
+    feedback: $feedback-colors,
+    neutral: $neutral-colors,
+);

src/styles/tools/_dictionaries.scss

@@ -0,0 +1,49 @@
+@use "sass:list";
+@use "sass:map";
+@use "../settings/dictionaries";
+@use "string" as rui-string;
+
+@function _get-category-by-value($value, $dictionaries) {
+    @each $category, $values in $dictionaries {
+        @if list.index($values, $value) {
+            @return $category;
+        }
+    }
+
+    @error
+        "Supplied value \""
+        + $value
+        + "\" not found in any category ("
+        + map.keys(dictionaries.$colors)
+        + ")";
+}
+
+@function _get-text-color-modifier($modifier) {
+    @if $modifier == "dark" {
+        @return "light";
+    } @else if $modifier == "light" {
+        @return "dark";
+    }
+
+    @return $modifier;
+}
+
+@mixin generate-colors($prefix, $component-name, $modifier, $properties, $inherit-link-color: false) {
+    .isRootColor#{rui-string.capitalize($modifier)} {
+        @each $property in $properties {
+            --#{$prefix}local-#{$property}:
+                var(
+                    #{"--" + $prefix + $component-name + "--" + $modifier + "__" + $property}
+                );
+        }
+
+        @if $inherit-link-color {
+            $color-category: _get-category-by-value($value: $modifier, $dictionaries: dictionaries.$colors);
+            $text-modifier: _get-text-color-modifier($modifier);
+
+            --#{$prefix}local-link-color: var(--rui-color-#{$color-category}-#{$text-modifier});
+            --#{$prefix}local-link-color-hover: var(--rui-color-#{$color-category}-#{$text-modifier}-hover);
+            --#{$prefix}local-link-color-active: var(--rui-color-#{$color-category}-#{$text-modifier}-active);
+        }
+    }
+}

src/styles/tools/_string.scss

@@ -1,7 +1,10 @@
-// Author: Hugo Giraudel
-
 @use "sass:string";
 
+@function capitalize($string) {
+    @return string.to-upper-case(string.slice($string, 1, 1)) + string.slice($string, 2);
+}
+
+// Author: Hugo Giraudel
 @function replace($string, $search, $replace: "") {
     $index: string.index($string, $search);