From 8c4c9cedaf6fc5a79009e82816ec747ae8a60ee7 Mon Sep 17 00:00:00 2001 From: Adam Kudrna Date: Mon, 26 Aug 2024 18:56:41 +0200 Subject: [PATCH] Introduce color collections for generative styling of components --- mkdocs.yml | 1 + src/docs/foundation/collections.md | 24 ++++++++++++++++++++++++ src/docs/foundation/colors.md | 20 ++++++++------------ src/docs/foundation/design-tokens.md | 8 +++----- src/styles/settings/_collections.scss | 9 +++++++++ 5 files changed, 45 insertions(+), 17 deletions(-) create mode 100644 src/docs/foundation/collections.md create mode 100644 src/styles/settings/_collections.scss 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..3fa1358f 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 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 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, +);