Introduce 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
+
+- Components can support one or more collections from a collection category.
+  Refer to the documentation for each component to see which collections are
+  available.
+- 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.
+
+## 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,
+);