Introduce color collections 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'
+          - 'Collections': 'docs/foundation/collections.md'
           - 'Colors': 'docs/foundation/colors.md'
           - 'Typography': 'docs/foundation/typography.md'
           - 'Spacing': 'docs/foundation/spacing.md'

src/docs/foundation/collections.md

@@ -0,0 +1,24 @@
+# Collections
+
+Collections are lists of available values that can be used to customize the
+appearance of components, such as colors, sizes, and placement. Collections are
+used to ensure consistency across the design system.
+
+## General Guidelines
+
+- If an option from a collection is used in a component, all other options from
+  the same collection must be available for use in that component too.
+- Components can support one or more collections from a collection category.
+  Refer to the documentation for each component to see which collections are
+  available.
+
+## Colors
+
+The following color names are designed for use in components that support the
+`color` prop:
+
+| Collection | Available values                                       |
+|------------|--------------------------------------------------------|
+| Action     | `primary`, `secondary`, `selected`                     |
+| Feedback   | `success`, `warning`, `danger`, `info`, `help`, `note` |
+| Neutral    | `light`, `dark`                                        |

src/docs/foundation/colors.md

@@ -227,23 +227,17 @@ primary border.
 
 ## Applying Colors
 
-Components can apply colors above using one or more following color groups.
+Components can apply colors above using one or more following approaches.
 
-### Component Colors
+### Color Collections
 
 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 Collections][collection-colors] are always
+used. There is always a reasonable default color for the component in question
+that can be changed to any of supported collection values through the `color`
+prop.
 
 ### Validation States
 
@@ -258,3 +252,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.
+
+[collection-colors]: /docs/foundation/collections#colors

src/docs/foundation/design-tokens.md

@@ -10,9 +10,7 @@ organizations.
 design system needs. React UI uses CSS custom properties as a primary storage
 format for design tokens.
 
-## Design Token Types
-
-### Global Tokens
+## Global Tokens
 
 Global tokens represent the basic, context-agnostic values in your design
 language. They define color palettes, typography scales, or spacing values,
@@ -24,7 +22,7 @@ without binding them to any semantic meaning.
 }
 ```
 
-### Semantic Tokens
+## Semantic Tokens
 
 Semantic tokens define roles and decisions that give the design system its
 character. They communicate the intended purpose of a global token and are often
@@ -36,7 +34,7 @@ reused by component tokens.
 }
 ```
 
-### Component Tokens
+## Component Tokens
 
 Component tokens represent the values associated with a component. They often
 inherit from semantic tokens, but are named in a way that narrows down their

src/styles/settings/_collections.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/_collections.scss

@@ -0,0 +1,49 @@
+@use "sass:list";
+@use "sass:map";
+@use "../settings/collections";
+@use "string" as rui-string;
+
+@function _get-category-by-value($value, $collections) {
+    @each $category, $values in $collections {
+        @if list.index($values, $value) {
+            @return $category;
+        }
+    }
+
+    @error
+        "Supplied value \""
+        + $value
+        + "\" not found in any category ("
+        + map.keys(collections.$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, $collections: collections.$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);