diff --git a/mkdocs.yml b/mkdocs.yml index 651715ea..e07315fd 100644 --- a/mkdocs.yml +++ b/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' diff --git a/src/docs/foundation/collections.md b/src/docs/foundation/collections.md new file mode 100644 index 00000000..939deefc --- /dev/null +++ b/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` | diff --git a/src/docs/foundation/colors.md b/src/docs/foundation/colors.md index 32d6c9ed..52e5b43b 100644 --- a/src/docs/foundation/colors.md +++ b/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 color collections. -### 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 diff --git a/src/docs/foundation/design-tokens.md b/src/docs/foundation/design-tokens.md index 21b93923..07e2f728 100644 --- a/src/docs/foundation/design-tokens.md +++ b/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 diff --git a/src/styles/settings/_collections.scss b/src/styles/settings/_collections.scss new file mode 100644 index 00000000..64b718d8 --- /dev/null +++ b/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, +); diff --git a/src/styles/tools/_collections.scss b/src/styles/tools/_collections.scss new file mode 100644 index 00000000..35c67741 --- /dev/null +++ b/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); + } + } +} diff --git a/src/styles/tools/_string.scss b/src/styles/tools/_string.scss index f0dde40c..b8dc32b9 100644 --- a/src/styles/tools/_string.scss +++ b/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);